Order Lifecycle

A reverse pickup order follows this flow:

Code
┌──────────────────┐
│ Order Placed     │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐    ┌───────────┐
│ Assigned for     │───▶│ Cancelled │
│ Pickup           │    └───────────┘
└────────┬─────────┘          ▲
         │                    │
         ▼                    │
┌──────────────────┐          │
│ Out for Pickup   │──────────┘
└────────┬─────────┘
         │
         ├────────────────────┐
         ▼                    ▼
┌──────────────────┐  ┌──────────────┐
│ Pickup           │  │ Pickup       │
│ Successful       │  │ Failed       │
└────────┬─────────┘  └──────┬───────┘
         │                   │
         ▼              (rescheduled,
┌──────────────────┐   re-enters flow)
│ Received at Hub  │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Returned to      │
│ Seller/Warehouse │
└──────────────────┘

States

These are the primary states. The API reference documents additional intermediate states (e.g. Not Contactable, QC Failed, On Hold) that you may encounter in tracking responses and webhooks.

Every state has a code and a display string. Match on the code — the display strings differ between the tracking API and webhooks for the same state, so they aren't a reliable thing to branch on.

A pickup doesn't always succeed on the first attempt. Alongside cid, the states nc (customer not contactable), na (not attempted), on_hold and qc_failed all mean the order is still live and will be reattempted. Further states appear on the return leg: recd_at_dc, rts_in_process, rts_nd, rto_nd, reopen and lost. Log an unrecognised code rather than failing on it — the set grows over time.

One display string is worth calling out. Tracking reports both rts_d and rto_d as Returned To Client, so the display string won't tell you whether the item reached the seller or your warehouse. Webhooks do distinguish the two. Either way, read the code.

Return Types

• RTS (Return to Seller): Item goes directly to the seller's address. Use return_type: "seller".
• RTO (Return to Origin): Item goes to a client warehouse/hub. Use return_type: "origin".

Webhooks

Shadowfax sends real-time POST callbacks whenever an order transitions state. Configure your webhook URL in the SFX 360 Partner Portal.