Copy page

Core

Orders

Manage the full lifecycle of forward delivery orders — creation, updates, and cancellation.

Placing a Forward Order

Submit a POST request with the customer's address, pickup location, return address, and item details. Fields are flat at the top level: customer_details, order_details, pickup_details, return_details (return_type: seller or origin — required), and product_details.

See Place Forward Order in the API Reference for the full request schema and field descriptions, and Order Types for how required fields shift across Marketplace, Warehouse, D2D, and MPS.

Check Serviceability before placing an order to confirm the delivery pincode is covered.

Payment Modes

Mode	Behavior
prepaid	Customer has already paid. cod_amount must be 0.
cod	Cash on Delivery. cod_amount must be > 0.

E-Way Bill

Required when product_value exceeds ₹50,000. Must be exactly 12 characters. At least one SKU must include a seller_details.gstin_number when product value >= ₹50,000.

Idempotency

If you submit the same client_order_id twice, the API returns the existing order instead of creating a duplicate. This makes retries safe.

Cancelling an Order

Cancel a forward order before it has been delivered. Pass the AWB number or client_order_id as request_id.

Code
curl -X POST https://dale.staging.shadowfax.in/api/v3/clients/orders/cancel/ \
  -H "Authorization: Token your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "SF1234567890",
    "cancel_remarks": "Customer requested cancellation"
  }'

Once cancelled, the order cannot be reactivated.

For MPS orders, cancel the parent AWB — a child AWB cannot be cancelled individually, and cancelling the parent cancels every child shipment with it.

See Cancel Order in the API Reference.

Updating Order Details

Update customer, pickup, or order details before dispatch. Send only the fields you want to change — all fields except awb_number are optional.

What You Can Update

Section	Fields
delivery_details	Contact number, address, pincode, coordinates
pickup_details	Contact number, address, pickup slot (Marketplace only)
return_details	Return address, contact, email
order_details	cod_amount, eway_bill_number, return_eway_bill_number, invoice_number, actual_weight, volumetric_weight, product_value, total_amount, gst_details
status_update	Trigger RTO, RTS, or reopen a failed delivery for another attempt

Restrictions

Once an order reaches a terminal status — delivered, RTO-D, RTS-D, or cancelled — nothing about it can be updated. Beyond that, a few sections have their own cutoff points:

• Once the shipment is in the RTO/RTS return journey: delivery_details and return_details can no longer be changed, and cod_amount can't be changed either (also true if the order was placed as COD to begin with).
• Once the item has been picked up: pickup_details can't be changed for Marketplace/customer-pickup orders (it's never editable for Warehouse orders, at any point). Pickup slot fields only apply to Marketplace in the first place.
• While still in the pickup phase: you can't yet trigger status_update (RTO, RTS, or reopen_ndr) — the shipment needs to have moved past pickup first.
• MPS orders: always update the parent AWB, never a child — updating a child AWB directly is rejected. To change an individual package, use the parent AWB's child_shipments field.

Code
curl -X POST https://dale.staging.shadowfax.in/api/v3/clients/order_update/ \
  -H "Authorization: Token your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "awb_number": "SF1234567890",
    "delivery_details": {
      "contact": "9999888877",
      "customer_address": "101 Residency Road, Bangalore",
      "pincode": "560025"
    }
  }'

See Update Order in the API Reference for the full field reference.

Reopening a Failed Delivery

When a delivery attempt fails, the order moves to a hold status (see Order Lifecycle). Reopen it to trigger another delivery attempt:

Code
curl -X POST https://dale.staging.shadowfax.in/api/v3/clients/order_update/ \
  -H "Authorization: Token your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "awb_number": "SF1234567890",
    "status_update": {
      "status": "reopen_ndr"
    }
  }'

You can also update the delivery address or contact number before reopening NDR to increase the chance of successful re-delivery.