Track shipments
Get status updates by webhook, poll as a fallback, and show your customers a clear tracking page.
- Product
- APIShipping Engine API
- Section
- Guides
- Reading time
- 7 min read
Goal: keep each shipment's status up to date in your system, and show your customers where their parcel is, in words they understand.
Before you start:
- You have booked at least one shipment and stored its shipment code (
SHP-…). See Book a shipment. - Your API key has
READ_ORDER. To register a webhook it also needsMANAGE_WEBHOOKS.
Webhooks first, polling second
Webhooks tell you about a change within seconds and cost you nothing to wait for. Use polling only to catch up after downtime or to double-check, never as your main source.
Receive status changes by webhook
Register one HTTPS endpoint for your organisation and Shipping Engine sends a signed
POSTeach time a shipment changes. Set it up with the Webhooks guide, then handle at least these events:Event Status after it Typical action shipment.pending_pickupPENDING_PICKUPShow "waiting for pickup"; show the driver for instant couriers. shipment.in_transitIN_TRANSITTell the customer the parcel is on its way. shipment.deliveredDELIVEREDClose the order on your side. shipment.problem_detected,shipment.pickup_failedPROBLEM_SHIPMENTAlert your team. shipment.cancelledCANCELLEDMark the shipment cancelled. shipment.rts_confirmed…shipment.rts_deliveredRTS_…The parcel is going back to the sender. Every event carries
shipment_code,booking_id(the order code) andawb, so you can find the shipment in your database. The full list is in Webhook events.webhook-handler.js // After verifying the signature (see /en/docs/api/webhooks/verify-signatures): app.post('/webhooks/shipping', async (req, res) => { const event = JSON.parse(req.rawBody); const status = event.data?.status ?? event.status; // shipment.dispatched is flat await db.shipments.update({ code: event.shipment_code }, { status, lastEventAt: new Date() }); res.sendStatus(200); // answer fast; do slow work in a queue });Events can arrive out of order. Never move a shipment back from a final status (
DELIVERED,RTS_DELIVERED,CANCELLED) because an older event arrives late.Poll the shipment list as a fallback
GET /b2b/shipmentslists your shipments, newest first. Use it after your webhook endpoint was down, or in a scheduled job that re-checks open shipments.Query Meaning statusOne status, for example IN_TRANSIT.startDate,endDateFilter on when the shipment was created. ISO 8601 with offset, for example 2026-11-01T00:00:00+07:00.orderCode,courierCodeExact order code, courier code. searchFree text (up to 100 characters). Matches the shipment code, airway bill, order code, or the receiver's name or phone number. limitPage size. Default 25, maximum 100. cursorThe nextCursorof the previous page.curl -s -G "$FASTRAC_API/b2b/shipments" \ -H "Authorization: Bearer $FASTRAC_TOKEN" \ --data-urlencode "status=IN_TRANSIT" \ --data-urlencode "startDate=2026-11-01T00:00:00+07:00" \ --data-urlencode "limit=100"InboundResponse (trimmed) { "statusCode": 200, "message": "Shipments retrieved.", "data": { "count": { "PENDING_PICKUP": 3, "PENDING_DROPOFF": 1, "IN_TRANSIT": 12, "DELIVERED": 240, "CANCELLED": 4, "RTS": 1 }, "shipments": [ { "id": 88231, "code": "SHP-261120-D4E5F6", "orderCode": "FSO-261120-A1B2C3", "airwayBill": "CGK1234567890", "trackingUrl": "https://…", "courierCode": "JNE", "courierServiceName": "JNE Reguler", "status": "IN_TRANSIT", "createdAt": "2026-11-20T03:12:44.000Z", "recipient": { "name": "Budi Santoso", "phoneNumber": "081298765432", "fullAddress": "Jl. Braga No. 8, Kota Bandung" }, "cursor": "ODgyMzE=" } ], "nextCursor": "ODgyMzE=" } }countgives totals per status for the date range you asked for (it ignores the other filters), so you can draw a dashboard without paging through everything.RTSadds up shipments being returned. Shipments of orders that were never paid are not listed.Get one shipment's history
GET /b2b/shipments/{code}/detailsreturns everything stored about one shipment, includinghistories(each status change with its time and description),packageDetailsand, for instant couriers,driverDetails.curl -s "$FASTRAC_API/b2b/shipments/SHP-261120-D4E5F6/details" \ -H "Authorization: Bearer $FASTRAC_TOKEN"This reads what Shipping Engine already knows. It doesn't contact the courier.
Ask the courier for a live status (sparingly)
GET /b2b/shipments/track/{code}asks the courier for its latest tracking. You can pass the shipment code or the airway bill.curl -s "$FASTRAC_API/b2b/shipments/track/CGK1234567890" \ -H "Authorization: Bearer $FASTRAC_TOKEN"InboundResponse (trimmed) { "statusCode": 200, "data": { "currentStatus": "IN_TRANSIT", "trackingUrl": "https://…", "courier": "JNE", "service": "JNE Reguler", "histories": [ { "timestamp": "2026-11-20T10:02:00.000Z", "status": "IN_TRANSIT", "description": "Paket diterima di gudang Bandung", "location": "BANDUNG" } ] } }- It is slower than the other endpoints, because it waits for the courier.
- If the courier reports something new, the shipment is updated and the usual webhook is sent.
- If the courier can't be reached, you get the history Shipping Engine already has.
- Before the shipment has an airway bill, the shipment code returns
Shipment 'SHP-…' has not been dispatched yet.(400).
Use it when a person is looking, for example a Refresh button on your tracking page, not in a loop over all shipments.
Show a tracking page to your customer
The simplest option is to link to
trackingUrl, the courier's own tracking page. It can benullfor some couriers or until the courier provides it, so build a fallback page from your stored status and history.Translate statuses into words your customer understands:
Status English label Indonesian label CONFIRMEDOrder received Pesanan diterima PENDING_PICKUPWaiting for courier pickup Menunggu dijemput kurir PENDING_DROPOFFBeing prepared for shipping Sedang disiapkan untuk dikirim IN_TRANSITOn the way Dalam perjalanan DELIVEREDDelivered Telah diterima PROBLEM_SHIPMENTDelayed, we're looking into it Terkendala, sedang kami periksa CANCELLEDCancelled Dibatalkan RTS_CONFIRMED,RTS_TRANSITReturning to sender Sedang dikembalikan ke pengirim RTS_PROBLEM_SHIPMENTReturn delayed Pengembalian terkendala RTS_DELIVEREDReturned to sender Telah kembali ke pengirim Show
etdRangefrom the booking as an estimate, and the airway bill so the customer can also check on the courier's own website. See Shipment statuses for what each status means.
How often to poll
Couriers report progress at their own pace, and some only a few times a day. Polling faster doesn't make updates arrive sooner.
| What | Recommended |
|---|---|
| Main source | Webhooks. |
Catch-up job over GET /b2b/shipments | Every 30–60 minutes, only for open statuses, with limit=100. |
Live tracking (/track) for one shipment | At most once every 30–60 minutes per shipment, and only on demand. |
Shipments in a final status (DELIVERED, RTS_DELIVERED, CANCELLED) | Stop polling them. |
Troubleshooting
| Symptom | What to check |
|---|---|
| No webhooks arrive | The endpoint's verificationStatus must be verified. See Webhooks. |
A shipment stays PENDING_DROPOFF | The parcel hasn't been scanned at the courier counter yet. |
A shipment stays PENDING_PICKUP after the pickup time | The courier may retry the pickup later. Contact support if it lasts more than a day. |
422 startDate cannot be later than endDate. | Swap the dates. Invalid dates return Invalid startDate filter. |
404 Shipment with code or airway bill '…' not found. | Check the code. Use the shipment code or the airway bill from the booking. |
Checklist
- A verified webhook endpoint updates your statuses.
- A catch-up job polls
GET /b2b/shipmentsevery 30–60 minutes and followsnextCursor. - Final statuses are never overwritten by older events.
- Live tracking is called on demand only.
- Customers see friendly labels, the airway bill and the
trackingUrlwhen there is one.
Was this page helpful?