ShipSeth for developers
Ship API
Book, label, manifest and track courier shipments from your own order system, and act on failed deliveries, without opening the dashboard.
- B2C forward & reverse
- Prepaid · COD · To-pay
- Signed webhooks
- Free sandbox
Idempotency-Key: 7f3c…e21a
{
"order_reference": "PU-ADM-2026-0042",
"payment_mode": "prepaid",
"consignee": { "pincode": "400001", … },
"parcel": { "weight": 0.5, … }
}{ "shipment_id": "…", "tracking_number": "981735709",
"canonical_status": "PROCESSING" }Quick answer
The ShipSeth Ship API lets your order system or CRM price a parcel, book it with a courier, print the label, manifest and invoice, follow every scan and act on failed deliveries, all without opening the ShipSeth dashboard. You log in with your ShipSeth account to get a Bearer token. Rates work on a brand-new account; booking needs verified KYC. There is no API fee.
· Base URL https://api.shipseth.com/api/ext/v1
What can the ShipSeth Ship API do?
It covers the whole life of a B2C parcel, from quote to delivery or return, through one base URL and one token.
Set up once
Pickup warehouses, default warehouse, courier priority and your webhook.
- POST
/warehouses - PUT
/config
Price & book
Quote every courier for a lane, then create and book in one async call.
- POST
/rates - POST
/shipments
Print documents
One label or a merged PDF of 100, the courier pickup manifest, and your invoices.
- POST
/labels - POST
/manifests - POST
/invoices
Track
By our tracking number or the courier AWB, one at a time or 50 at once.
- GET
/shipments/track/{number} - POST
/shipments/track
Fix failed deliveries
Read the NDR and re-attempt, change address or phone, or return it. Cancel before pickup.
- POST
/shipments/{id}/ndr/action - POST
/shipments/{id}/cancel
Test without money
A test token books on a dummy courier; move test parcels through any status yourself.
- POST
/auth/login (test: true) - POST
/test/shipments/{id}/scan
A token can carry booking, tracking or both. Give your warehouse screen a tracking-only token and keep booking rights on the server that actually creates orders.
How do I get ShipSeth API access?
Register a free ShipSeth account and call the login endpoint with the same credentials; nobody has to switch the API on for you.
- Register at shipseth.com/register. No monthly fee, no plan to choose.
- Mint a token with
POST /auth/login, sending your account email (or phone) and password plus alabelsuch as "erp-prod". The secret is shown once. Save it in your secrets store, not in the repo. - Price straight away.
POST /ratesworks before KYC, so you can build the checkout or courier-selection screen on day one. - Build on the sandbox. Log in again with
"test": true. That token books on a dummy courier, gets aTEST…waybill, holds nothing in your wallet and never shows up in billing. - Finish KYC and accept the merchant agreement in the dashboard. Until both are done, every write call answers
403 kyc_requiredor403 merchant_agreement_required.
One catch: the token you get from the dashboard login is not a Ship API token. Sent to /api/ext/v1 it gets 403 not_a_ship_api_token. Always mint from /auth/login on the API itself.
What does a first shipment look like, call by call?
Six calls take an order from your system to a parcel in the courier's van; the example below uses a Delhi to Mumbai parcel.
| # | Call | What you send | What comes back |
|---|---|---|---|
| 1 | POST /auth/login | email, password, label | Bearer token and its abilities |
| 2 | POST /rates | 110001 → 400001, 1.2 kg, 20 × 15 × 10 cm, prepaid | options[], each with a rate_id |
| 3 | POST /shipments | the chosen rate_id, consignee, order_reference, an Idempotency-Key UUID | 202, status PROCESSING, a tracking number |
| 4 | webhook, or GET /shipments/track/{number} | nothing | status moves to MANIFESTED and the courier AWB fills in |
| 5 | POST /labels | the day's shipment_ids, size: 4x6 | one PDF with every label, ready for the thermal printer |
| 6 | POST /manifests | the same shipment_ids | the hand-over sheet the courier executive signs at pickup |
About that example box: at the common 5000 divisor it weighs 0.6 kg volumetric (20 × 15 × 10 ÷ 5000), so the 1.2 kg on the scale is what gets billed. Divisors differ by courier; run your own cartons through the volumetric weight calculator before you hard-code a default box size.
Step 3 is asynchronous on purpose. The 202 means we accepted the order and are talking to the courier. Do not print anything until step 4 shows MANIFESTED; a label call before that returns 422 not_booked.
Which shipment statuses will my system see?
Fourteen canonical statuses, the same for every courier, so you write one mapping instead of one per courier.
PROCESSINGMANIFESTEDPICKUP_SCHEDULEDPICKED_UPIN_TRANSITOUT_FOR_DELIVERYDELIVEREDNDRRTO_INITIATEDRTO_DELIVEREDCANCELLEDFAILEDLOSTDAMAGEDThe courier's own wording travels alongside in current_status, which is the field to show your support team. PROCESSING never fires a webhook. NDR is the one to wire into an alert: a delivery attempt failed and someone has to act, through POST /shipments/{id}/ndr/action. LOST and DAMAGED come from the courier's own scan and start a claim. Our NDR guide covers what to do next, and tracking notifications covers what your buyer hears at each stage.
Should I retry a failed create with the same Idempotency-Key?
Retry with the same key only when the failure was about timing or money; when the request itself was wrong, fix it and send a new key.
Every POST /shipments needs an Idempotency-Key header. We store the answer for 24 hours when it is final (a 2xx, a 422, a rate_unavailable or a KYC/agreement 403) and replay it if the same key comes back. Pick the code you got:
Retry with the SAME key
What it means: Your wallet balance minus active holds cannot cover this shipment's hold. data.required_paise and data.available_paise say by how much.
Do this: Recharge the wallet, then resend with the same key. This answer is not stored, so the retry is processed fresh.
The rule of thumb: generate the UUID when the order is created in your system and store it on the order row. A retry loop that makes a fresh UUID each time defeats the whole point; the API then answers 409 duplicate_order_reference rather than booking the order twice.
How does money move when the API books a shipment?
The create call puts a hold on your prepaid wallet for the quoted shipping cost, and the real debit only posts once the courier issues the waybill.
Your usable balance is the wallet balance minus every active hold. Example (illustrative figures): the wallet shows ₹1,500 and two API shipments are holding ₹420 and ₹380, so ₹700 is available. A third order quoted at ₹750 gets 402 insufficient_balance with required_paise: 75000 and available_paise: 70000. All amounts in the API are paise, never rupees with decimals.
payment_mode | Forward | Reverse pickup | When the hold turns into a charge |
|---|---|---|---|
| prepaid | Yes | Yes (only mode) | At MANIFESTED |
| cod | Yes, cod_amount above 0 | No | At MANIFESTED |
| to_pay | Yes, cod_amount 0 or absent | No | Released if delivered (the consignee paid freight); charged to you if it goes RTO |
A cancelled or failed shipment releases its hold, and a hold still open after 30 minutes is released by a sweep job. Cash collected on COD orders booked through the API follows the same Tuesday and Friday remittance runs as dashboard orders. For the full list of quote lines and wallet entries, see ShipSeth pricing.
How do ShipSeth webhooks work?
Set a webhook_url and secret with PUT /config and we POST a signed shipment.status event to your HTTPS endpoint each time a shipment's customer-facing status changes.
Check the X-ShipSeth-Signature header (t=<unix>,v1=<hex>) by computing HMAC-SHA256 of t + "." + raw body with your secret, and drop anything more than 300 seconds old. Compute it on the raw bytes before your framework parses the JSON; re-encoded JSON will not match. Code for PHP, Node.js and Python is on the webhooks guide page.
If your endpoint does not answer with a 2xx inside 10 seconds, we try again on this ladder:
| Attempt | Waits after the previous one | Time since first send |
|---|---|---|
| 1 | sent on the status change | 0 min |
| 2 | 1 minute | 1 min |
| 3 | 5 minutes | 6 min |
| 4 | 30 minutes | 36 min |
| 5 | 2 hours | 2 h 36 min |
After the fifth miss the delivery is marked exhausted. So a deploy that keeps your endpoint down for three hours loses events; pull them back with POST /webhooks/deliveries/{id}/retry or re-read the shipments with POST /shipments/track. Redirects are not followed, so point the URL at the final address.
What are the Ship API rate limits?
Limits are counted per token, except login, which is counted per IP and per username.
| Calls | Limit |
|---|---|
POST /auth/login | 5 a minute |
POST /rates | 120 a minute |
POST /shipments, /label, /labels, /manifests, /invoices | 60 a minute |
GET /shipments/track/{number}, POST /shipments/track | 300 a minute |
POST /shipments/{id}/ndr/action | 30 a minute |
Everything else | 120 a minute |
Separately, an account can have at most 50 shipments holding wallet money at once. A flash-sale import of 400 orders should be fed through a queue, not fired in parallel.
We use Shiprocket today. What changes?
Mostly the names. Each Shiprocket call has one ShipSeth equivalent, and a few take one call instead of two.
| Shiprocket | ShipSeth Ship API |
|---|---|
orders/create/adhoc + courier/assign/awb | POST /shipments (one call) |
courier/serviceability | POST /rates |
courier/generate/label | POST /labels |
manifests/generate + print | POST /manifests |
orders/print/invoice | POST /invoices |
courier/track/awb/{awb} | GET /shipments/track/{awb} |
NDR action | POST /shipments/{id}/ndr/action |
Two differences are deliberate: create answers 202 at once and the AWB arrives on the MANIFESTED webhook, and every webhook is signed. The integration playbook has the full status map, the retry rules and the go-live checklist we sign off with you.
Can I book returns or B2B freight through the API?
Returns yes, B2B freight no.
Send "direction": "reverse" with a return_reason and the consumer's address as the consignee; the warehouse becomes the return-to address. Reverse pickups are prepaid only and currently go through Delhivery and Ekart. B2B and LTL freight, where a lorry receipt and per-kg matrix pricing come in, is booked from the dashboard; the API answers 422 b2b_not_supported. If you are weighing that route, start with LTL vs PTL vs FTL.
One more rule the API enforces: any forward shipment with invoice_amount above ₹50,000 needs an eway_bill number in the body. The e-way bill guide explains when you need one for intra-state moves too.
Ship API FAQ
Is the ShipSeth API free to use?
Yes. There is no API fee and no monthly plan. You pay for each shipment you book from the same prepaid wallet the dashboard uses, at the rate the API quoted before booking.
Can I get rates from the API before my KYC is approved?
Yes. POST /rates works on a new account. Creating, cancelling, scheduling pickup, printing and NDR actions need verified KYC and an accepted merchant agreement; until then those calls return 403 kyc_required or merchant_agreement_required.
Can I test the API without spending money?
Yes. Log in with test set to true and the token gets the ship:test ability. Shipments made with it are booked on a dummy courier with a TEST waybill, take no wallet hold, and stay out of billing and COD remittance. Move them through any status with POST /test/shipments/{id}/scan; webhooks fire for each step, flagged is_test.
Can my system act on failed deliveries (NDR) through the API?
Yes. A failed attempt arrives as an NDR webhook. GET /shipments/{id}/ndr shows the reason and the 48-hour deadline, and POST /shipments/{id}/ndr/action asks the courier to re-attempt, changes the address or phone, or sends the parcel back (RTO).
We use Shiprocket today. How much changes?
Mostly names. Create-and-assign is one call here and answers 202 straight away, with the AWB arriving on the MANIFESTED webhook, and webhooks are signed. The integration playbook maps every status and call one-to-one and lists the go-live checks.
Does the Ship API support B2B or LTL freight?
No. The Ship API books B2C parcels only, forward and reverse. A request with shipment_type b2b returns 422 b2b_not_supported. B2B freight with a lorry receipt is booked from the ShipSeth dashboard.
How long does ShipSeth keep retrying a failed webhook?
Five attempts in all: the first send, then retries 1 minute, 5 minutes, 30 minutes and 2 hours apart. If your endpoint has not answered with a 2xx by the fifth try, the delivery is marked exhausted and you can re-queue it from the delivery log endpoint.
Free to register. No monthly fee. Pay per shipment from your wallet.
Create a free accountRead the quickstartInteractive API reference
Every endpoint, field and example response, generated from the OpenAPI 3.1 spec. Open full screen · openapi.yaml · openapi.json