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
POST /api/ext/v1/shipments
Idempotency-Key: 7f3c…e21a
{
  "order_reference": "PU-ADM-2026-0042",
  "payment_mode": "prepaid",
  "consignee": { "pincode": "400001", … },
  "parcel": { "weight": 0.5, … }
}
202 Accepted
{ "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
ship:booking

Price & book

Quote every courier for a lane, then create and book in one async call.

  • POST/​rates
  • POST/​shipments
ship:booking

Print documents

One label or a merged PDF of 100, the courier pickup manifest, and your invoices.

  • POST/​labels
  • POST/​manifests
  • POST/​invoices
ship:booking

Track

By our tracking number or the courier AWB, one at a time or 50 at once.

  • GET/​shipments/​track/​{number}
  • POST/​shipments/​track
ship:tracking

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
ship:booking

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
ship:test

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.

  1. Register at shipseth.com/register. No monthly fee, no plan to choose.
  2. Mint a token with POST /auth/login, sending your account email (or phone) and password plus a label such as "erp-prod". The secret is shown once. Save it in your secrets store, not in the repo.
  3. Price straight away. POST /rates works before KYC, so you can build the checkout or courier-selection screen on day one.
  4. Build on the sandbox. Log in again with "test": true. That token books on a dummy courier, gets a TEST… waybill, holds nothing in your wallet and never shows up in billing.
  5. Finish KYC and accept the merchant agreement in the dashboard. Until both are done, every write call answers 403 kyc_required or 403 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.

#CallWhat you sendWhat comes back
1POST /auth/loginemail, password, labelBearer token and its abilities
2POST /rates110001 → 400001, 1.2 kg, 20 × 15 × 10 cm, prepaidoptions[], each with a rate_id
3POST /shipmentsthe chosen rate_id, consignee, order_reference, an Idempotency-Key UUID202, status PROCESSING, a tracking number
4webhook, or GET /shipments/track/{number}nothingstatus moves to MANIFESTED and the courier AWB fills in
5POST /labelsthe day's shipment_ids, size: 4x6one PDF with every label, ready for the thermal printer
6POST /manifeststhe same shipment_idsthe 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.

BookingPROCESSINGMANIFESTED
PickupPICKUP_SCHEDULEDPICKED_UP
On the wayIN_TRANSITOUT_FOR_DELIVERY
DeliveredDELIVERED
Needs actionNDRRTO_INITIATEDRTO_DELIVERED
StoppedCANCELLEDFAILEDLOSTDAMAGED

The 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_modeForwardReverse pickupWhen the hold turns into a charge
prepaidYesYes (only mode)At MANIFESTED
codYes, cod_amount above 0NoAt MANIFESTED
to_payYes, cod_amount 0 or absentNoReleased 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:

AttemptWaits after the previous oneTime since first send
1sent on the status change0 min
21 minute1 min
35 minutes6 min
430 minutes36 min
52 hours2 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.

CallsLimit
POST /auth/login5 a minute
POST /rates120 a minute
POST /shipments, /label, /labels, /manifests, /invoices60 a minute
GET /shipments/track/{number}, POST /shipments/track300 a minute
POST /shipments/{id}/ndr/action30 a minute
Everything else120 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.

ShiprocketShipSeth Ship API
orders/create/adhoc + courier/assign/awbPOST /shipments (one call)
courier/serviceabilityPOST /rates
courier/generate/labelPOST /labels
manifests/generate + printPOST /manifests
orders/print/invoicePOST /invoices
courier/track/awb/{awb}GET /shipments/track/{awb}
NDR actionPOST /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 quickstart

Interactive API reference

Every endpoint, field and example response, generated from the OpenAPI 3.1 spec. Open full screen · openapi.yaml · openapi.json

Loading the interactive reference…