Integration Best Practices & Flow Guide

This guide provides a foundational checklist of all major flows and responsibilities for integrating with RyderShip via API. It is written for a customer's technical team or third-party integrators.

In this article:

Overview
1. Item & Inventory Management Flows
2. Order Management Flows
3. Inbound Flows
4. Fulfillment & Shipping Flows
5. Value-Added Services (VAS) Flows (If Applicable)
6. Wholesale/EDI Flows (if Applicable)
7. Returns Management Flows (If Applicable)
8. Manual Configurations/Subscriptions
9. Testing & Validation in Sandbox
10. Production Readiness
11. Go-Live & Post-Go-Live Hypercare

Overview

As every brand's operations, systems, and business needs are unique, it is the customer's responsibility to define their own test cases at the beginning of the integration process. You know your business best. From storefront behavior to ERP rules, fulfillment logic, and any value-added service requirements. This document is intended to help guide your thinking and ensure all key integration flows are considered.

The Rydership team is here to support you throughout the process. Your Solutions Architect will work closely with you to troubleshoot issues, validate test transactions, and advise on best practices for successful implementation. Together, we'll ensure your integration is robust, efficient, and tailored to your specific needs.

1. Item & Inventory Management Flows

Item Creation/Import

Decide method for item creation (API vs. manual UI upload)
Determine required product attributes (dimensions, weight, descriptions, SKUs, etc.)
Handle item updates/edits

Inventory Management

Inventory snapshot via API (nightly/periodic download)
Real-time inventory adjustments via webhooks, e.g.: item.inventory_adjusted
Inventory reconciliation strategy (e.g., nightly vs. real-time delta handling)
Handling of damaged, returned, or expired inventory (if applicable)

2. Order Management Flows

Order Creation

Best practices
Build out the order flow from storefront > ERP > Rydership
Determine required fields (Item ID's, quantities, recipient info, shipping method, meta fields for special/extra data, if applicable)
Prevent order duplication
Order routing logic should occur upstream of Rydership

Order Modifications/Cancellations

Handling order/address changes
Cutoff time for edits before fulfillment begins
Support for pre-orders or split shipments
Support for order cancellation (by customer vs. by Rydership)

3. Inbound Flows

Shipnotice Handling

Creation of ASN/Shipnotice via API for all fresh inbound inventory
Shipnotice edits/updates (status, tracking, carrier details)
Webhook subscriptions for receipts: shipnotice.status_changed and shipnotice_item.quantity_received

4. Fulfillment & Shipping Flows

Order Shipments

Webhook subscription: order.shipped
Capturing tracking data and fulfillment confirmations
Handling multi-package or multi-shipment orders

Order/Packaging Rules

Set up any packing, shipping or routing rules (manual in UI)

5. Value-Added Services (VAS) Flows (If Applicable)

Define business requirements:
- Gift notes, gift wrap
- Custom inserts (e.g., marketing material)
- Packing slip template customization
- Wholesale/B2B needs (Nordstrom, Dillard’s, etc.)
- Embroidery requirements
Determine data exchange needed for VAS (integrate as needed with EZCom, etc.)
Special flags or meta fields to trigger VAS in order payload

6. Wholesale/EDI Flows (If Applicable)

Submit all retailer routing guides for any wholesale/EDI business (GS1 Label Field Mapping)
- We already have coverage for many popular retailers
- Review this document for retailer requirements: GS1 Label Field Mapping & Setup
- If you work with a retailer not already covered, we’ll need to configure required fields and GS1 label formats. This could add to your integration timeline
Wholesale Order Requirements
- Reference: Lifecycle of a Wholesale Order
- Order must be passed with order_type:wholesale
- Orders must have the shipping method text set to:
```
"shop_shipping_method_text": "Whiplash Needs Routing"
```
  - For international orders, use "Whiplash Needs Routing (International)".
  - These shipping methods must be pre-mapped in Rydership Shipping Method Mappings:
    - Domestic → Whiplash Needs Routing
    - International → Whiplash Needs Routing (International)

Wholesale Attributes Format

Pass wholesale-specific data at the order level in the wholesale_attributes object:

"wholesale_attributes": {
  "carrier_code": "string",
  "carrier_service": "string",
  "department": "string",
  "department_description": "string",
  "distribution_center": "string",
  "fob_code": "string",
  "gift_note": "string",
  "location": "string",
  "merchandise_type_code": "string",
  "partner": "string",
  "po_number": "string",
  "sender": "string",
  "vendor": "string",
  "vendor_number": "string",
  "store": "string",
  "replenishment": "string",
  "start_date": "2025-08-24",
  "cancel_date": "2025-08-24",
  "store_address_attributes": {
    "address_1": "string",
    "address_2": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "string",
    "country_iso2": "string",
    "name": "string",
    "company": "string",
    "context": "string",
    "phone": "string",
    "address_type": "string"
  }
}

Returned Fields
- All required wholesale fields will be included in:
  - The order.shipped webhook payload
  - The GET /order/{order_id} API response

7. Returns Management Flows (If Applicable)

Return creation via API (or via partner e.g. Loop)
Return routing logic (disposition instructions)
Capturing return receipt webhook: consumer_return.completed

8. Manual Configurations/Subscriptions

Packing/Routing Rules
Configure carriers (Parcel team will support)
Map Shopping Cart ship methods to Official Method (Parcel team)
Subscribe to relevant webhooks

9. Testing & Validation in Sandbox

Pre-Testing Setup:

Create and share test scenario tracker between your team and RyderShip.
Use the attached Test Scenarios for E2E Testing Template.
Add Users in Sandbox
Authenticate via the API (OAuth2)
Choose a subset of your Items to test with. Items created and inventory populated
Webhooks subscribed
Manual rules, VAS flags, and routing logic configured in Sandbox UI
Shipping methods configured with Parcel team (carrier accounts added)

Test Flow Coverage:

End-to-end order flows
End-to-end shipnotice flows
Order edit/cancel scenarios
Shipnotice update scenarios
Inventory adjustment events
VAS scenarios (if applicable)
End-to-end return creation and processing flows
Digestion of webhooks

Validation:

Confirm expected behavior against each test scenario
Rydership team will process all orders, shipnotices, etc to validate flows
Shared test scenario tracker updated with status per test
Continued testing until all passing

10. Production Readiness

Configuration

Add Users in Production
Set up all rules and routing logic in Production UI
Re-create validated shipping methods and carriers (Parcel team coordination)
Subscribe to Production webhooks
Rebuild any needed API authentication flows
Import or create item catalog
Receive inventory via shipnotices

Golden Transaction

Execute 1-2 "live but staged" order transactions
Validate system end-to-end across both sides
Confirm inventory sync and webhook receipts

11. Go-Live & Post-Go-Live Hypercare

Cutover date/time confirmed
Monitor first 24–72 hours of orders and transactions closely
Email and Slack support

Test Scenarios for E2E Testing Template.xlsx10 KB