Requests and responses
Hosts, headers, the response envelope, errors, pagination, IDs and units used by every endpoint.
- Product
- APIShipping Engine API
- Section
- Core concepts
- Reading time
- 7 min read
In short
- JSON over HTTPS. Every success is wrapped as
{ statusCode, message, data }; your payload is indata. - Errors are
{ statusCode, message, error }.messageis a list when several fields fail validation. - Money is whole Rupiah, weight is grams, size is centimetres, and times without an offset are WIB.
Base URLs
| Environment | API host |
|---|---|
| Sandbox | https://sandbox-api.fastrac.example |
| Production | https://api.fastrac.example |
Paths start directly after the host, for example https://api.fastrac.example/b2b/orders. There is no
version prefix in the path. Always use https://. See Use the sandbox.
Headers
| Header | When | Value |
|---|---|---|
Authorization | Every authenticated call | Bearer <access_token>. See Authentication. |
Content-Type | Calls with a body | application/json |
Accept | Optional | application/json |
Request bodies can be up to 1 MB.
Success responses
Every successful response has the same envelope:
{
"statusCode": 200,
"message": "Shipments retrieved.",
"data": { "...": "..." }
}| Field | Meaning |
|---|---|
statusCode | The HTTP status, repeated in the body. |
message | A short, human-readable result, for example Request successful. or Resource created successfully. Don't parse it. |
data | The result: an object, a list, or nothing for actions such as cancellations. |
A list endpoint that finds nothing still returns 200, with an empty list. Region endpoints then say
Request successful. data not found.
Errors
Errors have their own shape, without data:
{
"statusCode": 422,
"message": "Insufficient balance.",
"error": "InsufficientBalanceException"
}| Field | Meaning |
|---|---|
statusCode | The HTTP status. |
message | What went wrong, as a string, or a list of strings for validation errors. Log it. |
error | A short error name, such as Bad Request or InsufficientBalanceException. |
code | Present on a few errors that you may want to handle in code, such as PICKUP_SCHEDULE_EXPIRED, PICKUP_SCHEDULE_NOT_QUOTED and SHIPPING_RATE_EXPIRED. |
Validation errors
When the body or query fails validation, you get 400 and message is a list, one entry per
problem. Each entry starts with the path of the field:
{
"statusCode": 400,
"message": [
"packages.0.weight must not be greater than 100000",
"destinations.0.subdistrictId must be a number string"
],
"error": "Bad Request"
}Handle message as either a string or a list.
Unknown fields are dropped
Fields the endpoint doesn't know are silently removed before your request is processed. You get
no error. A typo such as "insurence": true is therefore ignored, and you may get a different error
about the field you meant, or a result you didn't expect. Check field names against the
API reference.
Status codes
| Status | Meaning | Retry? |
|---|---|---|
200 | Success. | — |
201 | Created, for example a rate or an order. | — |
400 | The request is invalid, or the action isn't possible. Read message. | No. Fix the request. |
401 | Missing, invalid or expired token. | Once, with a new token. |
403 | Your key's role lacks a permission, or the resource isn't yours. | No. |
404 | Not found, for example an unknown shipment or no courier for a route. | No. |
422 | Valid request, but not allowed now: for example a wrong state or a bad date range. | No, until the cause is fixed. |
500 | Unexpected error on our side. | Reads: yes, with backoff. Orders: check first, see Go-live. |
Full list of messages: Errors.
Pagination
List endpoints such as GET /b2b/shipments and
GET /b2b/user-balance/logs use a cursor:
| Parameter | Meaning |
|---|---|
limit | Items per page. Default 25, maximum 100. |
cursor | Leave it out for the first page. For the next page, send the nextCursor from the previous response. |
The response has nextCursor. When it is null, you have reached the last page. Treat the cursor as
an opaque string: don't build or change it yourself, and keep the other filters the same between pages.
Region search (GET /b2b/region/find) works the same way, with a
default limit of 20 (maximum 100).
This loop reads every delivered shipment from November 2026:
cursor=""
while :; do
page=$(curl -s -G "$FASTRAC_API/b2b/shipments" \
-H "Authorization: Bearer $FASTRAC_TOKEN" \
--data-urlencode "status=DELIVERED" \
--data-urlencode "startDate=2026-11-01T00:00:00+07:00" \
--data-urlencode "endDate=2026-11-30T23:59:59+07:00" \
--data-urlencode "limit=100" \
${cursor:+--data-urlencode "cursor=$cursor"})
echo "$page" | jq -c '.data.shipments[] | {code, airwayBill, status}'
cursor=$(echo "$page" | jq -r '.data.nextCursor // empty')
[ -z "$cursor" ] && break
doneIDs
| Object | Format | Example | Use it to |
|---|---|---|---|
| Shipping rate | SR- + 8 characters | SR-7KQ2M9XA | Book: shippingRateCode in POST /b2b/orders. |
| Order | FSO-YYMMDD-XXXXXX | FSO-261120-A1B2C3 | Cancel every shipment in the order. |
| Shipment | SHP-YYMMDD-XXXXXX | SHP-261120-K7Q2MX | Read, track, cancel and simulate one shipment. Webhooks send it as shipment_code. |
| Airway bill | Set by the courier | JX1234567890 | Track with the courier, or with GET /b2b/shipments/track/{code}. Can change: see shipment.airway_bill_updated. |
| Subdistrict | Numeric string | 3174091001 | subdistrictId in rate requests. |
Responses also contain numeric id fields. Store and use the codes above; they are what the
endpoints take.
Units and formats
| What | Format | Example |
|---|---|---|
| Money | Whole Rupiah, integer. No decimals. | 12984 = Rp 12.984 |
| Currency | Always IDR | "currency": "IDR" |
| Weight | Grams | 800 = 0,8 kg |
| Dimensions | Centimetres | { "length": 20, "width": 15, "height": 10 } |
| Coordinates | Decimal degrees | -6.2297, 106.8536 |
| Phone numbers | Indonesian numbers | 081234567890 or +6281234567890 |
| Booleans | JSON true / false, not strings | "insurance": false |
Time
- Send times in ISO 8601 with an offset, for example
2026-11-21T10:00:00+07:00. Times without an offset are read as WIB (Asia/Jakarta, UTC+7). - Responses return timestamps in ISO 8601, usually in UTC (
2026-11-20T09:15:00.000Z). Convert them to WIB before showing them to Indonesian customers. - Business rules that depend on the clock, such as how far ahead a pickup must be booked, use WIB.
- Webhook payloads use a different format. See Webhook events.
Message language
Response and error messages are mostly in English. A few come from Indonesian sources and are in
Indonesian, for example some pickup schedule errors, courier status descriptions in shipment
histories, and balance log descriptions such as Tagihan retur (RTS) resi …. Show your own text to
end users, and use statusCode, error and code in your logic rather than the wording of message.
Was this page helpful?