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_ORDERpermission. - Your balance (
shippingCredit) covers the shipping price. Top up from the dashboard if needed. You can check it withGET /b2b/user-balance. - You have the
subdistrictIdof the sender and receiver addresses.
- 1subdistrictId
YouShipping Engine
Find the region
Turn each address into the ID of its subdistrict.
GET/b2b/region/find
- 2shippingRateCode
YouShipping Engine
Get rates
Describe the parcel and route. Get a price from every courier.
POST/b2b/shipping-rate
- 3airwayBillYou are here
YouShipping Engine
Create the order
Book the rate your customer picked. The courier is booked for you.
POST/b2b/orders
- 4
Shipping EngineYou
Track
Shipping Engine calls your webhook each time the status changes.
EVENTshipment.* webhooks
→ status
Get a shipping rate
Request rates as in the Quickstart and pick one. Keep three things from it:
From the rate Why 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 withShipping rate code 'SR-…' have expired.Request a new rate and book with the new code.Choose how the courier gets the parcel
Set
shippingOptions.fulfillmentMethod:Value What happens What 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). OptionallyshippingOptions.schedule.The service must support the method you pick. Otherwise the order is rejected with
Courier service '…' (…) does not support pickup.(ordropoff).For pickup,
scheduleis the pickup time in ISO 8601, for example2026-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.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 outcoordinateandschedule.Field Required Notes sender.name,sender.emailYes Shown to the courier. sender.phoneNumberorsender.whatsappNumberOne of them An Indonesian number, for example 081234567890.sender.coordinateFor regular PICKUPlatitudeandlongitudeas strings.receivers[]Yes, at least one name,phoneNumber,addressNote,label,stopSequenceare all required.addressNoteis a hint for the courier, such as a landmark.shippingOptionsNo Leave out to use the default: drop-off for regular couriers. packages[]No shippingRatePackageCodefrom the rate, with an optionalpackageNote.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.
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:
Field Use 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_PICKUPorPENDING_DROPOFFonce booked.Check every shipment's
status. If the courier rejected the booking outright, the call still succeeds but that shipment comes backCANCELLEDand its price is refunded to your balance. Quote again and book a new order for it.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_TRANSITonce 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:
- Read the
Reasonpart of the message. If it isInsufficient balance., top up first. - Request a new rate. The old code may expire before you are ready.
- 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 empty | A 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
DROPOFForPICKUPfrom what the rate supports; send coordinates for pickup. - Send pickup times with a
+07:00offset, at least 15 minutes ahead. - Save the order code, shipment code and airway bill.
- Check each shipment's
status:CANCELLEDmeans 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/ordersblindly. Check first.
Was this page helpful?