Shadowfax Exchange API

API for exchange orders — deliver a new item to the customer and pick up the old one in a single rider visit.

An exchange order creates both a forward delivery and a reverse pickup together — if either fails validation, neither is created. The pickup and delivery hubs must be the same location, so the rider can complete both legs in one trip.

Authentication

Exchange supports both Token and OAuth2 authentication (OAuth tokens expire after 1 hour). See Authentication for the full setup, including how to generate credentials.

Exchange Order Flow

Code
Client places exchange order (fwd + rev pair)
    → Shadowfax validates both orders together
    → Serviceability checked — pickup and delivery hubs must match
    → Both orders created together, or neither is
    → Rider picks up old item AND delivers new item in one visit
    → Status updates sent via webhooks for both legs

How It Works

An exchange combines:

• Forward order: New item from seller/warehouse → customer
• Reverse order: Old item from customer → seller/warehouse

Both orders share the same customer_details and are linked internally. The system verifies that the pickup and delivery hubs are co-located so the rider can handle both in one trip.

Exchange Order States

The forward and reverse orders each have their own status lifecycle. See the Order Lifecycle guide for how each progresses.

Idempotency

If you send the same client_order_id combination within 10 minutes, the cached response is returned instead of creating duplicate orders.

Constraints

• Pickup and delivery hubs must be the same location
• Both forward and reverse orders are validated together — if either fails, neither is created
• AWB numbers are auto-assigned for both orders if not provided