Order and shipment lifecycle
How an order and its shipments move from booking to delivery, return or cancellation, and which status to rely on.
- Product
- APIShipping Engine API
- Section
- Core concepts
- Reading time
- 9 min read
In short
- An order groups one or more shipments and is paid once. Each shipment is one parcel, one courier and one airway bill (AWB).
POST /b2b/ordersvalidates, pays and books the courier in a single call. A successful response already contains each shipment'sairwayBill.- Track delivery with the shipment status, not the order status. Webhooks tell you when it changes.
Orders and shipments
You book shipping by creating an order. The order holds one shipment per shippingRateCode you send.
| Order | Shipment | |
|---|---|---|
| ID format | FSO-YYMMDD-XXXXXX | SHP-YYMMDD-XXXXXX |
| What it represents | One checkout: everything you book and pay for together | One parcel carried by one courier service |
| Paid | Once, for all its shipments | Its priceDetail.totalPrice is part of the order payment |
| Has an airway bill | No | Yes, airwayBill and trackingUrl once booked |
| Status to watch | Rarely needed | Yes: delivery progress lives here |
| Cancel | cancelOrder cancels all its shipments | cancelShipment cancels just one |
Mixing rules
All shipments in one order must be either COD or non-COD. Different couriers and destinations are fine. See Insurance and COD.
What happens when you create an order
POST /b2b/orders runs the whole booking synchronously. By the
time you get a response, each step below has either finished or failed.
- 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
| Step | What Shipping Engine does | If it fails |
|---|---|---|
| 1. Validate | Checks every shippingRateCode (exists, not expired, service still available), fulfilment method, pickup schedule, sender coordinates, vehicle capacity and COD rules. | 400 with the reason. Nothing is created or charged. |
| 2. Create | Saves the order (DRAFT) and one shipment per rate (WAITING_FOR_PAYMENT). | — |
| 3. Pay | Deducts the totalPrice of every non-COD shipment from your shipping credit, in one step. COD orders deduct nothing. Order becomes CONFIRMED, shipments CONFIRMED. | 400 Payment failed, but order 'FSO-…' was created successfully. Reason: Insufficient balance. The order stays DRAFT and nothing is charged. |
| 4. Book the courier | Sends each shipment to its courier and stores the airway bill. Shipments become PENDING_PICKUP or PENDING_DROPOFF. | Temporary courier error: 400 Payment failed, but order 'FSO-…' was created successfully. Reason: …, the charge is refunded and the order goes back to DRAFT. Courier rejects the shipment outright: the order still succeeds, but that shipment is CANCELLED and refunded. |
| 5. Respond | Returns 201 with the full order, including airwayBill, trackingUrl and pickupSchedule for each shipment. | — |
Check every shipment in the response
A 201 means the order was paid. It does not guarantee that every shipment was booked. Loop over
data.shipments and treat a shipment with status: "CANCELLED" as not booked. Its price has
already been refunded to your balance.
After a failed order, create a new one with fresh rates. You can cancel the leftover DRAFT order
with cancelOrder. Nothing is refunded because nothing was paid.
Order status
The order status tells you whether the order was paid, not where the parcels are.
Order status | When you see it |
|---|---|
DRAFT | Created, but payment or courier booking failed. Nothing is charged. |
CONFIRMED | Paid and sent to the couriers. This is what a successful POST /b2b/orders returns. |
CANCELLED | You cancelled the order with cancelOrder and every shipment is cancelled. Cancelling shipments one by one leaves the order status unchanged. |
Use shipment status for delivery
The order stays CONFIRMED while its shipments are picked up, delivered or returned. To know
whether a parcel has arrived, read the shipment's status, or listen for
shipment webhooks.
Shipment status lifecycle
A shipment follows the main path below. It can leave the path to CANCELLED, PROBLEM_SHIPMENT or
the return (RTS) branch.
Rules that always hold:
DELIVEREDandRTS_DELIVEREDare final. Nothing changes them.- Once a shipment enters the return branch (
RTS_*), it never goes back to the normal path or toCANCELLED. - A failed pickup attempt that the courier will retry keeps the shipment in
PENDING_PICKUP. WAITING_FOR_PAYMENTandCONFIRMEDlast only for the duration of thePOST /b2b/orderscall when it succeeds.
Status table
status | Meaning | Terminal? | Can cancel? | Webhook event | What to do |
|---|---|---|---|---|---|
WAITING_FOR_PAYMENT | Created, not paid. Seen on orders whose payment failed. | No | Yes, nothing to refund | — | Create a new order, or cancel this one. |
CONFIRMED | Paid, courier not booked yet. | No | Yes, refunded | — | Wait. Booking happens within the same request. |
PENDING_PICKUP | Booked. Waiting for the courier to collect the parcel from the sender. | No | Yes, courier is asked first | shipment.dispatched when booked, then shipment.pending_pickup (also when a driver is assigned) | Have the parcel packed and labelled with the AWB. |
PENDING_DROPOFF | Booked. Waiting for you to drop the parcel at a courier counter. | No | Yes, courier is asked first | shipment.dispatched | Drop the parcel off and show the AWB. |
IN_TRANSIT | The courier has the parcel. | No | Request only: most couriers refuse after pickup | shipment.in_transit | Share trackingUrl with your customer. |
PROBLEM_SHIPMENT | The courier reported a problem: failed delivery, damage, loss, or an instant pickup that failed or expired. | No | Request only | shipment.problem_detected, or shipment.pickup_failed for a failed instant pickup | Read the latest history entry. Contact support if it doesn't move on. |
DELIVERED | The receiver has the parcel. | Yes | No | shipment.delivered | Done. For COD, see Balance and charges. |
CANCELLED | Cancelled by you, by the courier, or because booking was rejected. | Yes | Already cancelled (returns success) | shipment.cancelled | Check the refund in your balance logs. |
RTS_CONFIRMED | The courier is returning the parcel to the sender. | No | No | shipment.rts_confirmed | Contact the receiver. See Returns (RTS). |
RTS_TRANSIT | The parcel is on its way back. | No | No | shipment.rts_transit | Prepare to receive it. |
RTS_PROBLEM_SHIPMENT | A problem on the way back. | No | No | shipment.rts_problem_shipment | Contact support. |
RTS_DELIVERED | The parcel is back with the sender. | Yes | No | shipment.rts_delivered, and shipment.rts_billed if a return fee applies | Check for an RTS fee in your balance logs. |
A status change without its own event is sent as shipment.status_updated. The full mapping of each
courier's own codes is in Shipment statuses.
The return (RTS) branch
When a parcel can't be delivered, the courier sends it back to the sender. This is called return to
sender (RTS). The shipment moves through RTS_CONFIRMED, RTS_TRANSIT (and possibly
RTS_PROBLEM_SHIPMENT) to RTS_DELIVERED. Some couriers charge a return fee. See
Returns (RTS).
Problem shipments
PROBLEM_SHIPMENT means the courier flagged an issue it may still resolve. It is not final. A problem
shipment can continue to IN_TRANSIT or DELIVERED, or go to the return branch.
| Typical cause | What usually happens next |
|---|---|
| Receiver not home, wrong or incomplete address | The courier retries, or starts a return. |
| Parcel damaged or lost | The courier investigates. Contact support with the shipment code. |
Instant courier couldn't find a driver, or the booking expired (shipment.pickup_failed) | Cancel the shipment and book again. |
How statuses are updated
Shipping Engine learns about status changes in three ways. You don't have to do anything for the first two.
| Source | When | Notes |
|---|---|---|
| Courier updates | As soon as the courier reports an event | Most changes arrive this way. |
| Periodic checks | On a schedule, for shipments that are not final yet | Catches events a courier didn't push. |
| On-demand tracking | When you call trackShipment | Fetches the live status from the courier and may update the shipment. |
Every change that reaches the shipment triggers its webhook event. Prefer
webhooks over polling. If you poll, use
listShipments with a status filter rather than tracking each
shipment.
Events are not ordered
Webhooks can arrive out of order, and a status can be reported more than once. Use the shipment's
current status from retrieveShipment when in doubt. See
Delivery and retries.
Histories
Each shipment keeps a histories list: one entry per status change or courier event.
[
{ "status": "PENDING_PICKUP", "description": "Kurir dalam perjalanan ke lokasi pickup", "timestamp": "2026-11-20T03:15:00.000Z" },
{ "status": "IN_TRANSIT", "description": "Picked up by courier", "timestamp": "2026-11-20T06:42:00.000Z" }
]| Where | What you get |
|---|---|
retrieveShipment | histories[] with status, description, timestamp, plus driverDetails for instant couriers |
trackShipment | currentStatus and live histories[] with timestamp, status, description, location, straight from the courier |
Descriptions come from the courier and can be in Indonesian or English. Show them as they are; don't parse them.
Common mistakes
Treating the order status as delivery status
The order stays CONFIRMED after its shipments are delivered. Check each shipment's status.
Assuming a 201 means every shipment was booked
If a courier rejects one shipment, the order still succeeds but that shipment is CANCELLED and
refunded. Check the status of each shipment in the response.
Retrying a failed order with the same request
A failed order stays as DRAFT. Retrying creates a new order. Request new rates if the old ones
have expired, and don't retry on 400 without fixing the cause.
Was this page helpful?