Skip to Content
FastracDocs

Book a shipment

Quote a regular courier, create the order, and hand the parcel over with its airway bill.

Product
APIShipping Engine API
Section
Guides
Reading time
8 min read

Goal: book a regular courier (JNE, J&T, SPX and others) for one parcel, get the airway bill (resi), and either drop the parcel at a courier counter or have it picked up.

Before you start:

  • You can get an access token. See the Quickstart.
  • Your API key has the CREATE_ORDER permission.
  • Your balance (shippingCredit) covers the shipping price. Top up from the dashboard if needed. You can check it with GET /b2b/user-balance.
  • You have the subdistrictId of the sender and receiver addresses.
  1. 1subdistrictId

    YouShipping Engine

    Find the region

    Turn each address into the ID of its subdistrict.

    GET/b2b/region/find

  2. 2shippingRateCode

    YouShipping Engine

    Get rates

    Describe the parcel and route. Get a price from every courier.

    POST/b2b/shipping-rate

  3. 3airwayBill
    You are here

    YouShipping Engine

    Create the order

    Book the rate your customer picked. The courier is booked for you.

    POST/b2b/orders

  4. 4

    Shipping EngineYou

    Track

    Shipping Engine calls your webhook each time the status changes.

    EVENTshipment.* webhooks

    → status

  1. Get a shipping rate

    Request rates as in the Quickstart and pick one. Keep three things from it:

    From the rateWhy you need it
    shippingRateCodeIdentifies the quote. You book with it.
    isSupportDropOff, isSupportPickupTell you which handover methods the service allows.
    destinations[0].packages[].packageCodeOptional. Lets you refer to each package in the order.

    Book before the rate expires

    A rate is valid until validUntil, usually about 15 minutes. An expired code is rejected with Shipping rate code 'SR-…' have expired. Request a new rate and book with the new code.

  2. Choose how the courier gets the parcel

    Set shippingOptions.fulfillmentMethod:

    ValueWhat happensWhat you must send
    DROPOFFYou bring the parcel to a courier counter. Default for regular couriers.Nothing else.
    PICKUPThe courier collects the parcel from the sender address.sender.coordinate (latitude and longitude, as strings). Optionally shippingOptions.schedule.

    The service must support the method you pick. Otherwise the order is rejected with Courier service '…' (…) does not support pickup. (or dropoff).

    For pickup, schedule is the pickup time in ISO 8601, for example 2026-11-21T10:00:00+07:00. It must be at least 15 minutes ahead (Jakarta time, UTC+7). If you leave it out, the pickup is set to 15 minutes from now. A time without an offset is read as Jakarta time (WIB), so always send the offset. See Pickup scheduling.

  3. Create the order

    Send the rate code with the sender and receiver contacts. The address, courier, parcel and price come from the rate, so you don't send them again.

    curl -s -X POST "$FASTRAC_API/b2b/orders" \
      -H "Authorization: Bearer $FASTRAC_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "shipments": [{
          "shippingRateCode": "SR-7KQ2M9XA",
          "sender": {
            "name": "Toko Contoh",
            "email": "[email protected]",
            "phoneNumber": "081234567890",
            "coordinate": { "latitude": "-6.2262", "longitude": "106.8530" }
          },
          "receivers": [{
            "name": "Budi Santoso",
            "phoneNumber": "081298765432",
            "addressNote": "Pagar hitam, sebelah warung",
            "label": "Rumah",
            "stopSequence": 1
          }],
          "shippingOptions": {
            "fulfillmentMethod": "PICKUP",
            "schedule": "2026-11-21T10:00:00+07:00"
          },
          "packages": [{ "shippingRatePackageCode": "PKG-SR-7KQ2M9XA-01" }]
        }]
      }'

    For drop-off, send "shippingOptions": { "fulfillmentMethod": "DROPOFF" } and leave out coordinate and schedule.

    FieldRequiredNotes
    sender.name, sender.emailYesShown to the courier.
    sender.phoneNumber or sender.whatsappNumberOne of themAn Indonesian number, for example 081234567890.
    sender.coordinateFor regular PICKUPlatitude and longitude as strings.
    receivers[]Yes, at least onename, phoneNumber, addressNote, label, stopSequence are all required. addressNote is a hint for the courier, such as a landmark.
    shippingOptionsNoLeave out to use the default: drop-off for regular couriers.
    packages[]NoshippingRatePackageCode from the rate, with an optional packageNote.

    Booking is synchronous

    One call creates the order, pays for it from your balance and books the courier. When it returns, the shipment already has its airway bill. You never call a separate payment endpoint.

  4. Read the result

    A successful call returns 201 with the order:

    InboundResponse (trimmed)
    {
      "statusCode": 201,
      "message": "Resource created successfully.",
      "data": {
        "code": "FSO-261120-A1B2C3",
        "status": "CONFIRMED",
        "price": { "amount": 9099, "currency": "IDR", "codBilled": 0, "codDisbursement": 0 },
        "shipments": [
          {
            "code": "SHP-261120-D4E5F6", 
            "courierCode": "JNE",
            "serviceName": "JNE Reguler",
            "status": "PENDING_PICKUP", 
            "fulfillmentMethod": "PICKUP",
            "pickupSchedule": { "scheduledAt": "2026-11-21T10:00:00+07:00", "asSoonAsPossible": false },
            "airwayBill": "CGK1234567890", 
            "trackingUrl": "https://…",
            "isCod": false,
            "priceDetail": { "totalPrice": 9099, "currency": "IDR" }
          }
        ]
      }
    }

    Store these with your own order record:

    FieldUse it for
    data.codeThe order code (FSO-…). You need it to cancel the whole order.
    shipments[].codeThe shipment code (SHP-…). Use it to track, cancel and match balance logs.
    shipments[].airwayBillThe courier's tracking number (resi). Give it to your customer.
    shipments[].trackingUrlThe courier's tracking page, when the courier provides one. It can be null.
    shipments[].statusPENDING_PICKUP or PENDING_DROPOFF once booked.

    Check every shipment's status. If the courier rejected the booking outright, the call still succeeds but that shipment comes back CANCELLED and its price is refunded to your balance. Quote again and book a new order for it.

  5. Label the parcel and hand it over

    The Shipping Engine API doesn't generate printable shipping labels. Write or print the airway bill and the receiver's name, phone number and address on the parcel, so the courier can identify it.

    • Drop-off: take the parcel to a counter of the courier you booked and give them the airway bill.
    • Pickup: have the parcel ready at the sender address at the scheduled time. The courier collects it there.

    The shipment moves to IN_TRANSIT once the courier has the parcel. Follow it with webhooks or polling.

When payment or booking fails

If your balance is too low, or the courier can't be booked, the call returns 400 with this message:

{
  "statusCode": 400,
  "message": "Payment failed, but order 'FSO-261120-A1B2C3' was created successfully. Reason: Insufficient balance.",
  "error": "Bad Request"
}

Despite the wording, nothing was booked. The order stays in DRAFT, and any amount taken from your balance is refunded. Leave the draft order as it is. To recover:

  1. Read the Reason part of the message. If it is Insufficient balance., top up first.
  2. Request a new rate. The old code may expire before you are ready.
  3. Create a new order with the new rate code.

Draft orders don't appear in GET /b2b/shipments, and you don't need to cancel them.

Troubleshooting

Error (400)Cause and fix
Invalid shipping rate code provided.The code doesn't exist. Use shippingRateCode from a rate response.
Shipping rate code 'SR-…' have expired.Request a new rate and book with it.
Pickup shipments require sender coordinates.Add sender.coordinate, or use DROPOFF.
Courier service '…' (…) does not support pickup.Use DROPOFF, or pick a rate with isSupportPickup: true.
Courier service '…' is currently not available.The service was switched off after you quoted. Quote again and pick another option.
PICKUP_SCHEDULE_EXPIRED code: Pickup schedule must be at least 15 minutes ahead (Asia/Jakarta, UTC+7).Move schedule later, or leave it out.
shipments.0.receivers.0.addressNote should not be emptyA required field is missing. See Handle errors.

For other errors and whether to retry them, see Handle errors and retries.

Checklist

  • Book before validUntil, and quote again if it has passed.
  • Pick DROPOFF or PICKUP from what the rate supports; send coordinates for pickup.
  • Send pickup times with a +07:00 offset, at least 15 minutes ahead.
  • Save the order code, shipment code and airway bill.
  • Check each shipment's status: CANCELLED means the courier refused it.
  • On Payment failed, but order … was created, re-quote and create a new order.
  • Don't retry a timed-out POST /b2b/orders blindly. Check first.

Was this page helpful?

On this page