ShipAny API v1

One API. Every Courier.

Shipping infrastructure for ecommerce platforms, marketplaces, ERPs and SaaS products — domestic and international rates, booking, labels, tracking, NDR, returns, wallet and webhooks.

Open API Console Download Sandbox Kit View API Reference

Quick start

Live in Three Steps

Get API Access

Contact ShipAny to enable your API account, then sign in to the API Console — separate from the merchant dashboard.

Create a Sandbox Key

Generate a shipany_test_sk_… secret key in Console → API Keys. Keys are shown once — store them securely.

Start Integrating

Call sandbox endpoints with simulated couriers and labels — no live bookings, no wallet charges. Rotate to a live key when ready.

Download API Docs (PDF) Sandbox Kit (PDF)

Introduction

API Capabilities

The ShipAny v1 REST API is authenticated with API keys and scoped to your API account and isolated wallet. Base URL: https://shipany.in/api/v1

Rates API

Live multi-courier rates with actual, volumetric and chargeable weight.

Serviceability API

Pincode serviceability, pickup/delivery availability, COD and TAT.

Shipment API

Single and bulk booking with courier selection and idempotency.

Tracking API

Normalized tracking timelines by shipment ID or AWB.

Label API

PNG/PDF shipping labels with per-box support for heavy shipments.

Pickups & Manifests

Schedule pickups and generate manifests for handover.

NDR & RTO API

Act on delivery exceptions — reattempt, reschedule or return.

Returns API

Create reverse shipments, exchanges and replacements.

International API

Cross-border rates, booking, customs data, labels and invoices.

Wallet API

Balance, credit limit and full transaction ledger.

Webhooks

HMAC-signed lifecycle events with retries and replay.

Cancellation API

Cancel before pickup with automatic wallet refund.

Authentication

API Keys, Sandbox & Envelopes

X-API-Key header

Generate sandbox (shipany_test_sk_…) or live (shipany_live_sk_…) secret keys in the API Console. Keys are stored hashed, shown once at creation, and can be rotated or revoked instantly. Send the key with every request:

X-API-Key: shipany_test_sk_…

Sandbox mode

Sandbox keys return simulated couriers (sandbox_express, sandbox_surface, sandbox_heavy), simulated SBX… AWBs and real PDF labels — with zero live courier calls and zero wallet movement. Integrate and test end-to-end, then switch to a live key for production traffic.

Envelopes, request IDs & limits

· Every response uses a standard envelope: {success, data, request_id} or {success:false, error:{code,message,request_id}}.
· Every request carries an X-Request-ID header — include it when contacting support.
· Bookings accept an Idempotency-Key header — safe retries return the same shipment without duplicates.
· Default rate limit is 60 requests/minute per key; usage is reported via X-RateLimit-Limit / Remaining / Reset headers.
· Courier credentials never leave ShipAny servers — your application only talks to the ShipAny API.

Shipping

Get Rates & Create Shipments

Rates are quoted live from couriers that actually service the lane and weight — an empty quote list means no courier currently serves it. Bookings debit your API wallet atomically and refund automatically on cancellation before pickup.

POST/api/v1/domestic/ratesX-API-Key: shipany_test_sk_… · Content-Type: application/json

curl -X POST https://shipany.in/api/v1/domestic/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: shipany_test_sk_YOUR_KEY" \
  -d '{ "from_pincode": "110001", "to_pincode": "400001", "weight": 1.5, "length": 30, "breadth": 20, "height": 10, "payment_mode": "prepaid"}'

POST /v1/domestic/shipments — request body

{
  "order_id": "ORD-10042",
  "customer_name": "Aarav Shah",
  "phone": "9876543210",
  "address": "221, MG Road",
  "city": "Mumbai", "state": "Maharashtra", "pincode": "400001",
  "items": [{ "name": "Cotton T-Shirt", "qty": 2, "price": 499, "weight": 0.75 }],
  "weight": 1.5,
  "length": 30, "breadth": 20, "height": 10,
  "invoice_value": 998,
  "invoice_number": "INV-10042",
  "eway_bill": "123456789012",
  "receiver_gstin": "27ABCDE1234F1Z5",
  "customer_reference": "MY-REF-0042",
  "payment_mode": "prepaid",
  "pickup_address": {
    "name": "My Warehouse", "phone": "9876543210",
    "address": "Plot 12, Industrial Area",
    "city": "Delhi", "state": "Delhi", "pincode": "110001"
  }
}

Reference

Endpoint Reference

Rates & Serviceability

POST/v1/domestic/serviceabilityPincode serviceability, pickup/delivery availability, COD and TAT.

POST/v1/domestic/ratesLive multi-courier rates for a lane, weight, dimensions and payment mode.

POST/v1/international/serviceabilityDestination-country serviceability check.

POST/v1/international/ratesInternational multi-courier rates.

Shipments

POST/v1/domestic/shipmentsCreate a shipment — courier selection, AWB and wallet debit in one call.

POST/v1/domestic/shipments/bulkCreate multiple shipments in one request.

GET/v1/shipmentsList your shipments with status filters.

GET/v1/shipments/{shipment_id}Fetch one shipment with full detail.

POST/v1/shipments/{shipment_id}/cancelCancel before pickup with automatic wallet refund.

POST/v1/international/shipmentsCreate an international shipment with item-level customs data.

GET/v1/international/shipments/{shipment_id}Fetch an international shipment.

Drafts, Presets & Receivers

POST/v1/draftsSave or update a shipment draft — book it later with courier selection.

GET/v1/draftsList your saved shipment drafts.

GET/v1/drafts/{draft_id}Fetch one draft with its full payload.

DELETE/v1/drafts/{draft_id}Delete a draft.

GET/v1/package-presetsList saved package dimension presets.

POST/v1/package-presetsCreate a package preset (name, weight, L×W×H).

DELETE/v1/package-presets/{preset_id}Delete a package preset.

GET/v1/receivers/searchSearch repeat receivers by name or phone for autofill.

Labels & Documents

POST/v1/shipments/{shipment_id}/labelGenerate a PNG/PDF label (per-box for heavy shipments).

GET/v1/shipments/{shipment_id}/label/downloadDownload the generated label file.

GET/v1/international/shipments/{shipment_id}/labelInternational shipping label.

GET/v1/international/shipments/{shipment_id}/invoiceInternational customs invoice.

Tracking

GET/v1/shipments/{shipment_id}/trackingNormalized tracking timeline for one shipment.

GET/v1/tracking/{awb}Track directly by AWB number.

GET/v1/international/shipments/{shipment_id}/trackingInternational tracking timeline.

Pickups & Manifests

POST/v1/pickupsSchedule a pickup for one or more shipments.

GET/v1/pickups/{pickup_id}Pickup status and details.

POST/v1/pickups/{pickup_id}/cancelCancel a scheduled pickup.

POST/v1/manifestsGenerate a shipment manifest.

GET/v1/manifests/{manifest_id}Fetch or download a manifest.

NDR, RTO & Returns

GET/v1/ndrList non-delivery reports.

POST/v1/ndr/{shipment_id}/actionReattempt, reschedule, update address/phone, hold or request RTO.

GET/v1/rtoList RTO shipments and details.

POST/v1/returnsCreate a reverse shipment, exchange or replacement.

GET/v1/returns/{return_id}Return shipment status.

Pickup Addresses

POST/v1/pickup-addressesSave a pickup address and pre-register it with courier partners (production keys).

GET/v1/pickup-addressesList saved pickup addresses with courier registration status.

Wallet

GET/v1/wallet/balanceAPI wallet balance, credit limit and available credit.

GET/v1/wallet/transactionsFull transaction ledger with debit/credit entries.

Tracking

Track Shipments

GET/v1/tracking/{awb}

Returns the full shipment record with a normalized tracking timeline — every courier scan mapped to unified ShipAny statuses, scoped to shipments owned by your API account. For push updates, use webhooks instead of polling.

Operations

Labels, Pickups & Manifests

Labels are generated on demand as PNG or PDF — for heavy multi-box shipments each physical box gets its own label (per-dimension limit 306 cm per box). Schedule pickups for one or more shipments and generate manifests for warehouse handover via the pickups and manifests endpoints.

Operations

NDR, RTO & Returns

Non-Delivery Reports are listed via GET /v1/ndr with the failure reason. Act on them with POST /v1/ndr/{shipment_id}/action — reattempt, reschedule, update address/phone, hold or request RTO. Reverse shipments, exchanges and replacements are created via POST /v1/returns. Subscribe to ndr, rto_initiated and return_created webhook events to react in real time.

Webhooks

Real-Time Shipment Events

Event types

shipment.createdshipment.bookedawb.assignedpickup.scheduledpicked_upin_transitout_for_deliverydeliveredndrndr_resolvedrto_initiatedrto_in_transitrto_deliveredcancelledlostdamagedreturn_createdreturn_pickedreturn_deliveredwallet.debitedwallet.refundedtest.webhook

Signature verification

Every delivery includes X-ShipAny-Signature (sha256=… HMAC-SHA256 hex of the raw body with your endpoint secret), X-ShipAny-Event and X-ShipAny-Event-Id. Failed deliveries retry up to 6 times with backoff and can be replayed from the API Console.

import hmac, hashlib
expected = "sha256=" + hmac.new(
secret.encode(), raw_body, hashlib.sha256
).hexdigest()
assert hmac.compare_digest(expected, signature)

International

Cross-Border Shipping

International endpoints cover destination serviceability, multi-courier rates, booking with item-level customs data (description, HS code, quantity, value, country of origin), tracking, labels and customs invoices. Rates, transit times and customs requirements vary by destination and carrier.

Wallet

Balance & Ledger

GET/v1/wallet/balance

Your API wallet is isolated from any merchant wallet. Bookings debit atomically at the quoted rate; cancellations before pickup refund automatically. Admin-assigned credit limits let you ship now and settle later. GET /v1/wallet/transactions returns the full ledger, and wallet.debited / wallet.refunded webhooks keep your systems in sync.

Reference

Errors, Status & Changelog

CodeMeaning

400Bad request — invalid input such as a malformed pincode or out-of-range weight/dimension.

401INVALID_API_KEY — missing, invalid, expired or revoked X-API-Key.

402Insufficient API wallet balance to create the shipment.

403FORBIDDEN — account suspended, sandbox disabled, or key lacks the required permission.

404Resource not found — e.g. a shipment that does not belong to your API account.

422Validation failed — mandatory shipment fields are missing or invalid.

429Rate limit exceeded for your API key (default 60 requests/minute).

503COURIER_UNAVAILABLE — no courier could serve the request; no charge is made.

API Status

Live component health for the API, rates, booking, tracking, webhooks and wallet.

Changelog

v1 — rates, serviceability, domestic + international booking, labels, pickups, manifests, NDR/RTO, returns, wallet and HMAC webhooks.

Start Building With ShipAny

Connect your platform to a powerful shipping infrastructure.

Open API Console Contact Us