Developers

API for developers

Read tracking, book and cancel shipments from your own system: an ERP, a store or a warehouse app. Keys are issued by Shippbie; to get one, write to support@shippbie.com.

How it works

Base URL https://www.shippbie.com/api/v1. JSON in and out. Every request carries Authorization: Bearer <key>.

  • A reply is {"data": …} or {"error": {"code", "message", "retryable", "fields"}}. retryable says whether sending the same request again later is safe and may succeed; fields, when present, names each parameter or body field that was refused.
  • Headers on a reply: Cache-Control: no-store always; Retry-After on 429 RATE_LIMITED, 409 BOOKING_IN_PROGRESS, 409 REQUEST_IN_PROGRESS and 503 CARRIER_RATE_LIMITED; Idempotent-Replayed: true on a replayed booking or pickup; Allow on 405.
  • Every path and method answers in this envelope, an unknown path (404 NOT_FOUND) or method (405) included.
GET /ping
What the key is and what it may do: {ok, key, audience, can: {read, book, cancel}, client: {id} | null}.
GET /carriers
The carriers a key allowed to book can choose from: {carriers: [{id, name, needsPickup, takesPickupLocation, takesPickupRequests, autoPickup, services}]}. takesPickupLocation: the carrier collects from a pickup location registered on its account, named per booking as pickupLocation. takesPickupRequests: it collects from there only once a pickup is requested for it (see Pickups). autoPickup: Shippbie requests those pickups for this key's client by itself, as each parcel is booked; always false for an internal key. services is null, or the carrier's own services, each {name, upToGrams, mode}: upToGrams is the heaviest parcel it takes (null for any).
GET /pickup-addresses
The saved pickup addresses a booking can name as pickupCode: {pickupAddresses: [{code, label, city, state, pincode, isDefault, carriers: [{id, ready}], updatedAt}]}, by code. carriers are the ones you can book with, by their id from GET /carriers; ready: that carrier can collect from the address now. isDefault: the address a booking that says nothing of its pickup is collected from. updatedAt moves when the address, or a carrier's answer to it, changes. A client's key gets its own; an internal key every client's, each with client {code}, or one client's with ?client=CODE. Archived addresses are left out.
GET /shipments
The change feed of the key's shipments (see Catching up).
GET /shipments/{orderId}
One shipment with its timeline. Order IDs are trimmed and case-insensitive.
POST /shipments
Book with a carrier. Needs a key allowed to book. 201 {shipment}.
GET /shipments/{orderId}/label
The shipment's label, to print: one per box, as each box is its own shipment. Needs a key allowed to book. 200 {orderId, fileName, pdf}, or {orderId, url, expiresNote} only when Shippbie cannot get the PDF (see Labels).
POST /shipments/{orderId}/cancel
Ask the carrier to cancel. Needs a key allowed to cancel. 200 {cancellation, shipment}.
GET /pickups
Pickups for a range of days, newest first: {pickups: [{id, providerId, date, time, location, status, packageCount, carrierReference, message}], from, to} (see Pickups).
POST /pickups
Ask a carrier to collect from a pickup location. Needs a key allowed to book. 201 {pickup}, or 200 {pickup, existing: true} for one already there (see Pickups).

Examples

Replace sk_live_… with your key.

Check the key

Answers what the key is and what it may do. Touches no shipment.

curl https://www.shippbie.com/api/v1/ping \
  -H "Authorization: Bearer sk_live_…"

First sweep

Every shipment changed since the time you give, oldest change first. Leave updatedSince out to read everything. Keep following nextCursor while hasMore is true, and store the last nextCursor.

curl "https://www.shippbie.com/api/v1/shipments?updatedSince=2026-10-01T00:00:00Z&pageSize=100" \
  -H "Authorization: Bearer sk_live_…"

Every poll after that

Send back the last nextCursor you stored, with the same filters; while the one you stored is null, leave cursor out. hasMore false means you are caught up, to within about 30 seconds (see Catching up).

curl "https://www.shippbie.com/api/v1/shipments?cursor=<nextCursor>&updatedSince=2026-10-01T00:00:00Z&pageSize=100" \
  -H "Authorization: Bearer sk_live_…"

Track one order

The shipment and its whole timeline, by the Order ID this platform issued.

curl https://www.shippbie.com/api/v1/shipments/APH-2026-7912465 \
  -H "Authorization: Bearer sk_live_…"

List the carriers you can book with

Needs a key allowed to book. Each carrier's id is the providerId a booking sends; needsPickup says whether every booking must carry its pickup address; takesPickupLocation says whether it collects from a pickup location you name as pickupLocation; takesPickupRequests says whether it collects only once a pickup is requested, and autoPickup whether Shippbie requests them for you; services lists the carrier's own services to send as service.

curl https://www.shippbie.com/api/v1/carriers \
  -H "Authorization: Bearer sk_live_…"

List your pickup addresses

Your saved pickup addresses, by the code a booking sends as pickupCode, with the carriers each is ready for.

curl https://www.shippbie.com/api/v1/pickup-addresses \
  -H "Authorization: Bearer sk_live_…"

Book with a carrier

Needs a key allowed to book. Send a new Idempotency-Key for each order, and the same one again on every retry of it. Returns the booked shipment, with its Order ID and your reference. pickupCode names the saved pickup address the carrier collects from, such as your own warehouse code; without one, name the pickup location as pickupLocation for a carrier with takesPickupLocation, or add the pickup fields for a carrier with needsPickup (see Booking).

curl -X POST https://www.shippbie.com/api/v1/shipments \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c9a52-7b3e-4f7d-9a0e-2c6b1d8e4f10" \
  -d '{
    "providerId": "<an id from GET /carriers>",
    "reference": "YOUR-ORDER-1042",
    "pickupCode": "YOUR-WAREHOUSE-1",
    "paymentMode": "Prepaid",
    "weightGrams": 500,
    "consigneeName": "Priya Sharma",
    "consigneePhone": "9876543210",
    "consigneeAddress": "12 Park Street",
    "consigneePincode": "700016",
    "consigneeCity": "Kolkata",
    "consigneeState": "West Bengal"
  }'

Print a box's label

Needs a key allowed to book. Each box you book is its own shipment, with its own Order ID and its own label, so ask once per box. Returns the label as a PDF, base64-encoded; only when Shippbie cannot get the PDF, a link to it (see Labels).

curl https://www.shippbie.com/api/v1/shipments/APH-2026-7912465/label \
  -H "Authorization: Bearer sk_live_…"

Request a pickup

Needs a key allowed to book. Asks the carrier to collect from one of your pickup locations, for a carrier with takesPickupRequests: a day and a time in India time, and how many packages. Leave pickupLocation out for your default. Returns the pickup; if one is already open there, that one, with existing: true (see Pickups).

curl -X POST https://www.shippbie.com/api/v1/pickups \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2e4c7a-1d3f-4a6b-8c5e-7f0a2b4d6e81" \
  -d '{
    "providerId": "<an id from GET /carriers>",
    "pickupLocation": "Your Warehouse",
    "date": "2026-10-31",
    "time": "15:00",
    "packageCount": 12
  }'

List your pickups

Your pickups for a range of days, by the day each is for, newest first: the ones you requested and the ones Shippbie requested for your parcels.

curl "https://www.shippbie.com/api/v1/pickups?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer sk_live_…"

Find a booking by your own order number

Matches reference exactly, among the bookings Shippbie recorded, such as one whose reply never reached you. An empty list does not prove an order was never booked (see Retrying safely).

curl "https://www.shippbie.com/api/v1/shipments?reference=YOUR-ORDER-1042" \
  -H "Authorization: Bearer sk_live_…"

Cancel

Needs a key allowed to cancel. The carrier decides whether it still can be.

curl -X POST https://www.shippbie.com/api/v1/shipments/APH-2026-7912465/cancel \
  -H "Authorization: Bearer sk_live_…"

Catching up

GET /shipments is a change feed: oldest change first, resumed from a cursor. Reply: {shipments, pageSize, hasMore, nextCursor, serverTime}.

  • Shipments come in the order their updatedAt moved, oldest first; ties are broken in a fixed order carried inside the cursor. Shipments in a list carry no timeline.
  • Start with updatedSince, or with nothing to read everything. Follow nextCursor while hasMore is true, and store the last nextCursor. On the next poll send it back as cursor, with the same filters. hasMore false means you are caught up to about 30 seconds ago.
  • Changes from the last 30 seconds are returned as soon as they fit on a page, but the cursor stops short of them, so they come again on a later poll. If more than a page of shipments changed within those 30 seconds, the rest wait until they are older than that, and hasMore is false meanwhile. Nothing is skipped, and a shipment can arrive more than once: upsert by orderId. A nextCursor of null means nothing has settled yet; poll again the same way, without cursor (an empty one is refused).
  • Parameters: cursor; updatedSince (shipments whose updatedAt is at or after it); status (any case); reference (exact, up to 60 characters); pageSize (1 to 100, default 50). Each at most once. Anything else is refused, page included: it was replaced by the cursor, and there is no total.
  • serverTime is Shippbie's clock when it answered. Should you ever lose your cursor, restart with updatedSince set 30 seconds before the updatedAt of the last shipment you processed: times from Shippbie, never from your own clock. Some shipments then come again, and none is missed.
  • A parameter the API cannot read, an empty or repeated one included, gets 400 INVALID_QUERY, with fields naming it, and never a wider list than you asked for. Times need Z or an offset: send the + of an offset as %2B, as in updatedSince=2026-10-28T10:00:00%2B05:30.
  • A shipment deleted by Shippbie staff, or moved by them to another client, drops out of the feed without a final entry, and its Order ID then answers 404. So does one moved away from the login an internal key acts as.

Booking

POST /shipments with these fields. The client is always the key's own and cannot be chosen. A field this API does not know is refused, so a misspelling never books without its value.

providerId
Required. An id from GET /carriers.
reference
Your own order number, up to 60 characters, such as a delivery challan number: DC-2026-000016, or DC-2026-000016/2 for its second box. Optional and not unique. Returned on every reply, and searchable with ?reference=. The carrier's label prints it as the order reference, in the form that carrier takes: some take only letters and digits, up to 20, and write box 2 as B2. When the same reference is booked again with a carrier, after a cancellation say, or by another client, the label shows it with a short suffix, such as -2 or R2.
paymentMode
Required. Prepaid, COD or Pickup.
codAmount
1 to 500000. Required when paymentMode is COD.
declaredValue
1 to 10000000. Some carriers need it; for COD, codAmount stands in when it is left out.
weightGrams
Required. Whole grams, 1 to 1000000.
lengthCm, widthCm, heightCm
1 to 500. Some carriers need them, unless Shippbie has set a default box size for that carrier.
shippingMode
Surface or Express.
service
For a carrier that lists services: one of them, within its upToGrams. Left out, Surface picks the carrier's ground service where it has one, and otherwise the service goes by weight.
pickupCode
One of your saved pickup addresses, by its code: up to 40 letters, digits, dots, dashes, underscores or slashes, starting with a letter or digit, such as your own warehouse code. Any case; it is kept in upper case. GET /pickup-addresses lists them. The parcel is collected from that address: for a carrier with takesPickupLocation, at the pickup location it is set up under; for a carrier with needsPickup, from the address itself. A code you have no address under, sent with all seven pickup fields (and, for a carrier with takesPickupLocation, pickupLocation), saves that address under the code, on first use; two bookings sent at once with one new code save it once. Pickup fields sent beside a saved address must have its pickupPincode, and are then used as sent; the saved address is not changed. pickupLocation sent beside it must be the name it is set up under, unless the carrier has never taken that name: then yours replaces it, so a mistyped name can be corrected. Answered 422 VALIDATION_FAILED on pickupCode, with nothing booked, when no address of yours has the code and the whole address did not come with it, when the address is not set up with the carrier, or when the carrier cannot collect from it. Not for an internal key, whose bookings are for no client.
pickupLocation
For a carrier with takesPickupLocation: the name of the pickup location to collect from, as registered on the carrier's account for you, matched exactly, case and spaces included. Up to 160 characters. Required when you send any pickup field, unless your pickupCode names an address already set up with the carrier: an address alone never picks a location. Left out with neither pickupCode nor pickup fields: your default pickup address saved on Shippbie, by the name it is set up under with the carrier, else your default pickup location, else the carrier's default. Answered 422 VALIDATION_FAILED on pickupLocation, with nothing booked, when pickup fields come without it, when the name is another client's pickup location, when your default pickup address is not set up with the carrier, or when the carrier does not know the name; a name is never swapped for another. Beside pickupCode, see there. Other carriers ignore it. Returned on the shipment.
pickupName, pickupPhone, pickupAddress, pickupPincode, pickupCity, pickupState, pickupEmail
Where the parcel is collected. Required by a carrier with needsPickup, unless you send a pickupCode or Shippbie has saved a default pickup address for you: with none of these fields sent, that address is used (when the carrier would not take it, a 422 names the fields to send instead). A carrier with takesPickupLocation is not sent them and takes them only with pickupLocation or a pickupCode; a valid pickupPincode keeps the name, city, state and pincode as the shipment's origin (not on a reverse pickup). Other carriers ignore them. Phone 10 digits, pincode 6 digits; name up to 160, address 300, city and state 80, email 160 characters. A carrier with needsPickup may take less, in English letters and digits only: today's takes a pickup or delivery address of up to 90 characters, needs consigneeCity and consigneeState, needs declaredValue above 0 (for COD, codAmount stands in), needs lengthCm, widthCm and heightCm unless Shippbie has set a default box for it, and takes no reverse pickups (paymentMode Pickup). Anything it would not take is answered 422 VALIDATION_FAILED naming each such field, before the carrier is asked.
description
Up to 500 characters.
consigneeName
Required. 2 to 160 characters.
consigneePhone
Required. 10 digits.
consigneeAddress
Required. 5 to 300 characters.
consigneePincode
Required. 6 digits.
consigneeCity, consigneeState
Up to 80 characters each.

Retrying safely: Idempotency-Key

  • Send Idempotency-Key with every booking: one UUID per order, 1 to 255 visible ASCII characters, and the same key on every retry of that order. A key is remembered per API key for at least 30 days, so a new API key does not know the Idempotency-Keys sent with the one it replaces: before re-sending such an order under a new API key, look for it with ?reference=, and if it is not there, ask Shippbie before booking it again.
  • The same key and body after a success: 201 with the same shipment and Idempotent-Replayed: true. The carrier is not asked again.
  • The same key while the first request is still running, whatever the body: 409 BOOKING_IN_PROGRESS. Retry after Retry-After.
  • The same key with a different body after a success: 422 IDEMPOTENCY_KEY_REUSED, and that order is already booked. A field sent as null and one left out count as the same body.
  • After a failure in which nothing was booked (CARRIER_REFUSED, CARRIER_UNAVAILABLE, CARRIER_RATE_LIMITED, CARRIER_NOT_CONFIGURED, or a field you can correct), the same key may be sent again.
  • After BOOKING_OUTCOME_UNKNOWN or BOOKED_NOT_RECORDED the key keeps answering with that error, whatever the body (a corrected one included), and the carrier is not asked again. Do not book the order again until Shippbie confirms what happened; then use a new key. ?reference= cannot settle it: it finds only bookings Shippbie recorded, and these were not, so an empty list proves nothing.
  • Without the header, a retry can book a second parcel.

Cancelling

POST /shipments/{orderId}/cancel. Reply: {cancellation: {accepted, repeated, requestedAt, carrierMessage}, shipment}.

  • 200 means the carrier accepted the cancellation. The status becomes CANCELLED, or RETURNED for a parcel already on its way, once the carrier's tracking confirms it.
  • repeated is true when the carrier had already accepted a cancellation, or the shipment is CANCELLED: the carrier is not asked again. requestedAt is when the carrier first accepted, or null when the shipment was cancelled without a cancellation accepted through Shippbie (at the carrier, for example).
  • The carrier decides what can still be cancelled; a refusal is 422 CARRIER_REFUSED. carrierMessage, the carrier's own reply, is for internal keys only. Some carriers cannot be asked to cancel through Shippbie at all: their shipments answer 422 VALIDATION_FAILED, with no fields; contact Shippbie for those.
  • Two cancels of one shipment sent at once may both reach the carrier; requestedAt stays the first acceptance. Wait for the reply before sending another.
  • 502 CARRIER_UNAVAILABLE means the carrier did not confirm the cancellation, so it may already have gone through. Retrying is safe; a refusal on the retry can mean the first one worked, and the status becomes CANCELLED once the carrier's tracking confirms it.

Labels

GET /shipments/{orderId}/label. Each box you book is its own shipment, with its own Order ID and its own label: ask for each box's label by its Order ID, and print one per box. Needs a key allowed to book.

{"data": {"orderId": "APH-2026-7912465", "fileName": "APH-2026-7912465-label.pdf", "pdf": "JVBERi0xLjQK…"}}

{"data": {"orderId": "APH-2026-7912465", "url": "https://…", "expiresNote": "This link expires after a short time: …"}}
  • The label comes as a PDF whenever Shippbie can get it: kept from the booking, or downloaded from the carrier. pdf is the label itself, base64-encoded, to decode and print, or save as fileName (the Order ID, then -label.pdf). To print a delivery's boxes together, put their PDFs one after another in a single file.
  • Only when Shippbie cannot download it is the reply a link: url is the carrier's own link to the PDF, and expiresNote says how long it lasts, or is null. Download it straight away rather than storing the link, which may stop working within minutes. Check for pdf first.
  • Asking again is always safe, and gives the label again. A PDF Shippbie keeps from a booking is kept for 30 days at most, and not once the shipment is delivered or returned.
  • No label to give is 422 VALIDATION_FAILED, with no fields: the shipment is not booked with a carrier yet, it is cancelled or the carrier accepted its cancellation, or its carrier's labels cannot be printed through Shippbie (contact Shippbie for those). The message says which.
  • A carrier that does not give the label just now is 502 CARRIER_UNAVAILABLE or 503 CARRIER_RATE_LIMITED: retry shortly. One that has no label for the shipment is 422 CARRIER_REFUSED. Another client's Order ID is 404 NOT_FOUND, as on every endpoint.
  • The label is the carrier's own document, the one its courier scans: it shows the carrier and the AWB, which no other reply gives a client's key, and the consignee's name, address and phone. Keep it as carefully as the order.

Pickups

For a carrier with takesPickupRequests, a booking alone brings no van: the carrier collects from a pickup location once a pickup is requested there, for a day, a time and a number of packages. A pickup covers a location, not particular parcels.

  • A pickup is {id, providerId, date, time, location, status, packageCount, carrierReference, message}. date (YYYY-MM-DD) and time (HH:MM, 24-hour) are India time. carrierReference is the carrier's own id for it, or null until it gives one (it gives none when it already had a pickup there that day). A shipment's pickup is the same, without providerId and packageCount.
  • status: pending, being sent, or sent without a clear answer from the carrier (a timeout, say): Shippbie checks those with the carrier, and never asks again by itself, which could bring a second van; requested, the carrier took it (it may since have been collected, or its day passed); failed, nothing was raised: the carrier refused it or could not be reached, and message says why. A failed pickup is asked again with the next parcel booked for that location and day, or when you request it again; it keeps its id.
  • message: for a client's key, the carrier's own reason, or a sentence saying what happened, never naming the carrier; null when there is nothing to say.
  • Automatic pickups: where autoPickup is true (Shippbie switches it on for you, with your daily pickup time, 15:00 unless you ask for another), each parcel you book is given its pickup by Shippbie once the booking is recorded, after its reply: the pickup then reaches you through the change feed. The day is today when the parcel is booked at least 2 hours before your pickup time, otherwise the next day; there are none on a Sunday, so a parcel that misses Saturday's, or is booked on a Sunday, is collected on Monday. Later parcels for the same location join the pickup open there, whatever its day, and add to its count: the carrier is asked once. A reverse pickup (paymentMode Pickup) never gets one: the carrier collects it from the consignee.

Requesting one: POST /pickups

  • Body: providerId (required; a carrier with takesPickupRequests); pickupLocation (the pickup location's name, as for a booking; left out, your default pickup location; required for an internal key); date (required; today to 2 days ahead); time (required; not already past, today); packageCount (required; 1 to 5000). A field this API does not know is refused.
  • 201 {pickup}: raised, and requested, or pending while the carrier's answer is checked. 200 {pickup, existing: true}: a pickup is already open at that location, for that day or another (a carrier takes one open pickup per location), or that day's has been collected; the carrier is not asked again. A failed one for that day is asked again in its place (201, the same id), never returned. One there that is not yours and covers none of your parcels is not shown: 409 CONFLICT, with nothing raised; contact Shippbie.
  • A name that is not one of your pickup locations, or that the carrier does not know, gets the same 422 VALIDATION_FAILED on pickupLocation. The carrier refusing is 422 CARRIER_REFUSED; it being unreachable, 502 CARRIER_UNAVAILABLE. Nothing is raised on any of these.
  • Send an Idempotency-Key, as with a booking: the same key and body again get the same pickup, with Idempotent-Replayed: true, and the carrier is not asked again; while the first is still being sent, 409 REQUEST_IN_PROGRESS; with another body, 422 IDEMPOTENCY_KEY_REUSED. After a failure that raised nothing, the same key asks again. Without a key a repeat cannot raise a second pickup either: it finds the first (200, existing).

Reading them: GET /pickups

  • from and to, YYYY-MM-DD, inclusive, by the day each pickup is for. Left out, from 14 days ago and to 7 days ahead; at most 92 days apart. Each at most once; anything else gets 400 INVALID_QUERY. Reply: {pickups, from, to}, newest day first.
  • A client's key gets its own pickups, and any other covering its parcels; an internal key every client's, each with client {id, name, code}, or null for a pickup that is no single client's.

What a shipment carries

Both audiences get these. An internal key also gets carrier {code, name}, awb and client {id, name, code}, each possibly null.

orderId
The Order ID Shippbie issued, e.g. APH-2026-7912465.
reference
Your own order number from the booking, or null.
pickupLocation
The pickup location the carrier was told to collect from, by its registered name: the one the booking named, the one its pickupCode's address or your default pickup address is set up under, your default pickup location, or the carrier's default. null for a carrier without takesPickupLocation, and for shipments not booked through Shippbie.
pickup
null, or the pickup that collects it, for a carrier with takesPickupRequests: {id, date, time, location, status, carrierReference, message}, as GET /pickups gives it (see Pickups). updatedAt moves whenever it changes. A booking's own reply shows none yet when Shippbie requests the pickup itself: that follows the reply, and reaches you through the change feed.
status, statusUpdatedAt
Where the shipment is (one of the statuses below), and when the carrier reported it.
origin, destination
{city, state, pincode}, as far as they are known.
serviceType, pieces, weightKg, description
As booked, or as the carrier reports them.
bookedAt, expectedDeliveryAt, deliveredAt, returnedAt
ISO 8601 times, or null. expectedDeliveryAt is only ever the carrier's own estimate.
deliveryAttempts, lastLocation, lastEventAt
From the latest scans. lastLocation is in the carrier's own words.
isOverdue
Past the carrier's expected delivery and not finished. Worked out as you read it, so it can turn true without updatedAt moving.
tracking
{availability: LIVE | AWAITING | UNAVAILABLE, lastUpdatedAt, message}: how fresh the tracking is. It can change without updatedAt moving.
cancelRequestedAt
When the carrier accepted a cancellation asked for here, or null.
createdAt
When the shipment was registered here.
updatedAt
When anything here that you can see last changed, or the shipment became visible to you. Not when it was last checked: tracking can change without it.
timeline
On get, book and cancel only; newest first: [{status, description, location, occurredAt}]. description and location are the carrier's own scan text, with the AWB and other long numbers taken out. A status is null for a carrier update Shippbie does not classify; its description still says what happened.

Statuses

  • PENDINGAwaiting first update
  • MANIFESTEDManifested
  • PICKED_UPPicked up
  • IN_TRANSITIn transit
  • AT_ORIGIN_FACILITYAt origin facility
  • AT_DESTINATION_FACILITYAt destination facility
  • OUT_FOR_DELIVERYOut for delivery
  • DELIVERY_ATTEMPTEDDelivery attempted
  • DELIVEREDDelivered · final
  • DELAYEDDelayed
  • EXCEPTIONException
  • RETURN_IN_TRANSITReturning to origin
  • RETURNEDReturned · final
  • CANCELLEDCancelled · final

Errors

Act on the code, not the message: a client's key gets neutral wording, and messages may change.

CodeHTTPRetryableWhat to do
INVALID_QUERY400NoFix the query parameters named in fields.
INVALID_IDEMPOTENCY_KEY400NoSend 1 to 255 visible ASCII characters, e.g. a UUID.
UNAUTHORIZED401NoThe key is missing, wrong, revoked or expired, or its login or client is no longer active. Ask for a new key.
FORBIDDEN403NoThe key was not issued to book (which covers pickups and labels too), or to cancel.
NOT_FOUND404NoNo shipment with that Order ID for this key (or it was deleted), no active client with an internal key's ?client= code, or no such endpoint.
METHOD_NOT_ALLOWED405NoUse a method from the Allow header.
BOOKING_IN_PROGRESS409YesThe first request with this Idempotency-Key is still running. Retry after Retry-After.
REQUEST_IN_PROGRESS409YesThe first pickup request with this Idempotency-Key is still being sent to the carrier. Retry after Retry-After.
CONFLICT409NoRare. Contact Shippbie.
PAYLOAD_TOO_LARGE413NoKeep the body under 256 KB.
UNSUPPORTED_MEDIA_TYPE415NoSend Content-Type: application/json.
VALIDATION_FAILED422NoYour own input: fix the body fields named in fields. With no fields, on a cancel: that shipment's carrier cannot be cancelled through Shippbie; contact Shippbie. On a label: there is no label to give, and the message says why (see Labels).
IDEMPOTENCY_KEY_REUSED422NoThat key already booked a shipment, or raised a pickup, from a different body. If it is the same order, it is booked: do not send it with a new key. Only a new order (or pickup) needs a new key.
CARRIER_REFUSED422NoThe carrier said no: nothing was booked or raised, it would not cancel, or it has no label for the shipment. For a booking, check the address, pincode, weight and payment; for a pickup, the message gives the carrier's reason.
RATE_LIMITED429YesOver the key's requests per minute. Wait for Retry-After.
INTERNAL_ERROR500Yes for GET, cancel, a pickup and a keyed bookingRetry reads, cancels and pickups. Retry a booking only with its Idempotency-Key.
CONFIGURATION_ERROR500NoContact Shippbie.
CARRIER_UNAVAILABLE502YesA booking: the carrier could not be reached, or answered that it was unavailable (HTTP 503), so it is taken as not booked; retry shortly with the same Idempotency-Key. A pickup: the same, and nothing was raised; retry shortly. A cancellation: the carrier did not confirm it, so it may or may not have gone through; retry shortly (see Cancelling). A label: the carrier did not give it; retry shortly.
BOOKED_NOT_RECORDED502NoThe carrier booked it but Shippbie could not record it. Do not book the order again; contact Shippbie.
CARRIER_RATE_LIMITED503YesThe carrier asked us to slow down; nothing was booked, raised or cancelled. Wait for Retry-After.
CARRIER_NOT_CONFIGURED503YesShippbie's set-up for that carrier is wrong; nothing was booked, raised or cancelled. Retry once Shippbie has fixed it.
BOOKING_OUTCOME_UNKNOWN504NoThe carrier did not confirm the booking: a timeout, a carrier fault, or a lost connection; or the carrier already holds a parcel under your reference that was not booked through Shippbie, and it may be this order. Do not book the order again until Shippbie has checked.

Limits, privacy and keys

  • Each key has its own requests per minute, set when it is issued (10 to 1000, default 120) and shared by every endpoint. Over it the reply is 429 with Retry-After: wait, then retry.
  • JSON bodies up to 256 KB; pageSize up to 100; reference up to 60 characters; Idempotency-Key up to 255.
  • Booking, cancelling, requesting a pickup and fetching a label wait on the carrier: allow at least 60 seconds before your client gives up.
  • A client's key sees only that client's shipments, pickups and pickup addresses. Its shipment replies carry no AWB and no carrier field, its pickup addresses no carrier's own names for them, and its pickups' messages and error messages never name the carrier or carry an AWB; a pickup's message, and a refused pickup's error, give the carrier's own reason, and no other carrier wording reaches it. GET /carriers names the carriers a key allowed to book can choose from. Tracking is the carrier's own, though: timeline descriptions and locations, and lastLocation, are its scan text, with the AWB and other long numbers taken out. A label is the carrier's own document too, and nothing is taken out of it: it shows the carrier and the AWB (see Labels). Internal keys are for Shippbie's own systems.
  • Reading is always allowed; booking (and requesting pickups and labels) and cancelling only if the key was issued with them.
  • Keys are issued by Shippbie. A key stops working for good when Shippbie revokes it, when it expires, or when the Shippbie account it acts for is suspended, deleted, moved or has its password reset: ask Shippbie for a new one. A new key does not know the Idempotency-Keys of the old one (see Retrying safely).
  • A key is shown once, when it is issued. Keep it on your server, never in a web page or an app. If it leaks, tell Shippbie at once so it can be revoked and replaced.