APIs for integrating with Shadowfax logistics services.
Shadowfax handles last-mile delivery and reverse logistics (customer pickups) across India. Use these APIs to place orders, track shipments, and manage returns programmatically.
Authentication
Reverse Logistics supports both Token and OAuth2 authentication (OAuth tokens expire after 1 hour). See Authentication for the full setup, including how to generate credentials.
This reference covers Reverse (Pickup) orders — a customer return where a rider picks up from the customer and delivers to the seller or warehouse. For how this compares to Forward and Exchange orders, see Order Types.
Reverse Order Flow
Code
Webhooks are the push path. You can also pull an order's current state at any time with the Track API — use it to reconcile after downtime, or as a fallback if a callback was missed.
Return Types
- RTS (Return to Seller): Item goes directly to the seller's address. Use
return_type: "seller"— seller contact is required since the rider needs to coordinate handover. - RTO (Return to Origin): Item goes to a client warehouse/hub. Use
return_type: "origin"— typically a fixed location, contact is optional.
Pickup Order States
Primary States
These are the states your integration should handle. Build your order lifecycle logic around these.
| State | Description |
|---|---|
New | Pickup request received in Shadowfax system |
Assigned | Assigned to a pickup executive |
Out For Pickup | Pickup executive is en route to customer |
Picked | Item collected from customer |
Received | Item received at Shadowfax hub |
Returned To Client | Successfully delivered to seller (RTS) or warehouse (RTO) |
Cancelled | Order cancelled |
Cid | Customer not available — pickup rescheduled |
Not Contactable | Customer is unreachable |
Not Attempted | Pickup executive couldn't attempt pickup |
On Hold | Order held due to operational or client-side reasons |
QC Failed | Doorstep quality check failed |
Undelivered | Failed delivery attempt to seller/warehouse |
Lost | Item lost in transit |
Advanced States
Granular transit and processing states. Available in V4 tracking API for clients who need detailed shipment visibility.
| State | Description |
|---|---|
Received at Return DC | Item at return processing center |
Item added to Bag | Added to a manifest bag for transit |
Bag In Transit | Manifest bag in transit between facilities |
Bag Received at Via | Bag at intermediate facility |
Bag Received | Bag arrived at destination facility |
Bag in transit for return | Bag in transit for return leg |
Return to Seller initiated | RTS process started at processing center |
Received at RTS destination hub | Arrived at final hub before seller delivery |
Return Shipment Out for Delivery | Out for delivery to seller address |
Item Misrouted | Shipment reached wrong facility |
Pincode Updated | Destination pincode changed |
ReOpen | Order reopened for delivery attempt |
Push Callbacks (Webhooks)
Shadowfax sends real-time status updates to your server via a POST request whenever an order transitions to a new state.
Setup
Configure your webhook URL and custom headers in the Client Portal → Webhook tab. Your endpoint must be served over HTTPS. Shadowfax will POST to your URL with the headers you specify.
Payload Fields
| Field | Type | Description |
|---|---|---|
awb_number | string | Shadowfax tracking number |
order_id | string | Your client_order_id |
event_timestamp | string | ISO 8601 timestamp of the event |
current_location | string | Location where event occurred |
comments | string | Additional context about the event |
event | integer | Internal status ID |
status | string | Human-readable status display name |
otp_verified | string | Y, N, or NA — whether OTP was verified at pickup |
rider_name | string | Rider name (present on Out For Pickup events) |
rider_contact | string | Rider phone (present on Out For Pickup events) |
type | string | FWD for forward, REV for reverse |
recipient_info | object | Recipient details (present on delivered/rts_d events) |
qc_images | array | QC failure images (present on QC Failed events) |
attempt_number | integer | Pickup attempt number |
Sample Webhook Payload
Code
Migrating from V3 API
If you're migrating from the older v2/v3/clients/requests endpoint, here's the field mapping:
| V3 Field | V1 Pickup Field |
|---|---|
client_order_number | order_details.client_order_id |
client_request_id | order_details.awb_number |
price (root) | order_details.price |
total_amount (root) | order_details.total_amount |
eway_bill (root) | order_details.eway_bill |
address_attributes.phone_number | customer_details.contact |
address_attributes.address_line | customer_details.address |
seller_attributes | return_details with return_type: "seller" |
seller_attributes.phone | return_details.contact |
seller_attributes.address_line | return_details.address |
destination_pincode + warehouse_address | return_details with return_type: "origin" |
skus_attributes[].name | sku_details[].sku_name |
skus_attributes[].client_sku_id | sku_details[].sku_id |
skus_attributes[].invoice_id | sku_details[].invoice_no |
skus_attributes[].seller_details.regd_name | sku_details[].seller_details.seller_name |
skus_attributes[].seller_details.regd_address | sku_details[].seller_details.seller_address |
skus_attributes[].seller_details.state | sku_details[].seller_details.seller_state |
skus_attributes[].seller_details.gstin | sku_details[].seller_details.gstin_number |
skus_attributes[].taxes.total_tax_amount | sku_details[].taxes.total_tax_value |
skus_attributes[].additional_details.quantity | sku_details[].additional_details.quantity_value |
Token <api_token>