ShiprocketAPI

Forward order lifecycle

The happy-path flow for a forward (outbound) shipment on Shiprocket is:

  1. Create the order — POST /v1/external/orders/create/adhoc with buyer / seller addresses, item list, weight, and dimensions. Returns a Shiprocket order_id and shipment_id. Required top-level fields include order_id (your seller order id), order_date, pickup_location, billing_customer_name, billing_address, billing_city, billing_pincode, billing_state, billing_country, billing_email, billing_phone, order_items[], payment_method, sub_total, length, breadth, height, weight. Each entry in order_items[] needs name, sku, units, selling_price.

  2. Check serviceability (optional but recommended) — GET /v1/external/courier/serviceability/?pickup_postcode=...&delivery_postcode=...&weight=...&cod=0. Returns available couriers with ratings and rates. Use this to pick a courier before assignment.

  3. Assign courier and generate AWB — POST /v1/external/courier/assign/awb with shipment_id and (optionally) courier_id from the serviceability response. On success you receive an awb_code.

  4. Generate pickup — POST /v1/external/courier/generate/pickup with shipment_id (or [shipment_id_1, shipment_id_2] for bulk). Schedules the courier pickup.

  5. Generate documents (optional) — each call returns the URL of the generated PDF.

    • Label — POST /v1/external/courier/generate/label with shipment_id as an array. The AWB must already be assigned.
    • Invoice — POST /v1/external/orders/print/invoice with ids, an array of Shiprocket order ids.
    • Label and invoice in one PDF — POST /v1/external/courier/generate/label-invoice with shipment_ids, 1 to 200 shipment ids.
    • Manifest — POST /v1/external/manifests/generate with shipment_id as an array. The AWB must be assigned and pickup requested first. To print a manifest that is already generated, call POST /v1/external/manifests/print with order_ids, an array of Shiprocket order ids.

  6. Track — GET /v1/external/courier/track/awb/{awb_code} or GET /v1/external/courier/track/shipment/{shipment_id}. Alternatively subscribe to the tracking webhook for push updates.

Cancellation

Before AWB generation, cancel with POST /v1/external/orders/cancel passing ids: [order_id]. After AWB generation, the cancellation also sweeps the courier side and refunds any paid COD float where applicable.

Order status vs shipment status

  • Order status describes the seller's view of the order (new / cancelled / delivered).
  • Shipment status reflects the courier's view (pickup scheduled / in transit / out for delivery / delivered / RTO).

These diverge when, for example, a shipment is undeliverable and marked RTO but the underlying order is still active for refund processing.