Skip to Content
FastracDocs

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 needs MANAGE_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.

  1. Receive status changes by webhook

    Register one HTTPS endpoint for your organisation and Shipping Engine sends a signed POST each time a shipment changes. Set it up with the Webhooks guide, then handle at least these events:

    EventStatus after itTypical 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) and awb, 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.

  2. Poll the shipment list as a fallback

    GET /b2b/shipments lists your shipments, newest first. Use it after your webhook endpoint was down, or in a scheduled job that re-checks open shipments.

    QueryMeaning
    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 nextCursor of 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="
      }
    }

    count gives 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. RTS adds up shipments being returned. Shipments of orders that were never paid are not listed.

  3. Get one shipment's history

    GET /b2b/shipments/{code}/details returns everything stored about one shipment, including histories (each status change with its time and description), packageDetails and, 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.

  4. 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.

  5. Show a tracking page to your customer

    The simplest option is to link to trackingUrl, the courier's own tracking page. It can be null for 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:

    StatusEnglish labelIndonesian label
    CONFIRMEDOrder receivedPesanan diterima
    PENDING_PICKUPWaiting for courier pickupMenunggu dijemput kurir
    PENDING_DROPOFFBeing prepared for shippingSedang disiapkan untuk dikirim
    IN_TRANSITOn the wayDalam perjalanan
    DELIVEREDDeliveredTelah diterima
    PROBLEM_SHIPMENTDelayed, we're looking into itTerkendala, sedang kami periksa
    CANCELLEDCancelledDibatalkan
    RTS_CONFIRMED, RTS_TRANSITReturning to senderSedang dikembalikan ke pengirim
    RTS_PROBLEM_SHIPMENTReturn delayedPengembalian terkendala
    RTS_DELIVEREDReturned to senderTelah kembali ke pengirim

    Show etdRange from 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.

WhatRecommended
Main sourceWebhooks.
Catch-up job over GET /b2b/shipmentsEvery 30–60 minutes, only for open statuses, with limit=100.
Live tracking (/track) for one shipmentAt 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

SymptomWhat to check
No webhooks arriveThe endpoint's verificationStatus must be verified. See Webhooks.
A shipment stays PENDING_DROPOFFThe parcel hasn't been scanned at the courier counter yet.
A shipment stays PENDING_PICKUP after the pickup timeThe 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/shipments every 30–60 minutes and follows nextCursor.
  • Final statuses are never overwritten by older events.
  • Live tracking is called on demand only.
  • Customers see friendly labels, the airway bill and the trackingUrl when there is one.

Was this page helpful?

On this page