Placing Exchange Orders
An exchange order atomically creates both a forward delivery and a reverse pickup. The request body has three top-level sections — customer_details (shared, delivery address for the new item), fwd_order (new item: pickup, delivery, and SKU details), and rev_order (old item: pickup, return, and SKU details).
See Place Exchange Order in the API Reference for the full request/response schema and field descriptions.
Business Rules
E-Way Bill and GSTIN
fwd_order — required when product_value exceeds ₹50,000. eway_bill must be exactly 12 characters, and at least one SKU must include seller_details.gstin_number.
Payment Consistency
fwd_order.order_details.cod_amount must be 0 for payment_mode: prepaid, and greater than 0 for payment_mode: cod. rev_order has no payment mode — the reverse leg is always a pickup, not a paid transaction.
Hub Matching
Pickup and delivery hubs must be the same location.
Waiving QC on the Reverse Leg
Set qc_required to false on the reverse SKU at placement if it doesn't need quality-check verification before pickup. The field defaults to true.
Idempotency
If you send the same client_order_id combination (forward + reverse) within 10 minutes, the API returns the previously cached response — with message: "success" and the original order data — instead of creating duplicate orders. This is not an error condition. This makes retries safe.
Error Handling
A failure is signalled by message being "Failure", with the detail in errors. There is no machine-readable error code — branch on the HTTP status first, then on errors if you need to tell causes apart.
| Condition | HTTP Status |
|---|---|
| Request body failed validation — missing or invalid fields | 400 |
| Account not yet activated | 400 |
| Well-formed request rejected afterward by an allocation or business rule | 200 |
| Pickup and delivery hub don't match, or pincode not covered | 200 |
Note the last two: a rejected order can still come back as 200. Always check message rather than assuming a 200 means the order exists.
See Place Exchange Order in the API Reference for the full error schema.