Skip to Content
FastracDocs

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/orders validates, pays and books the courier in a single call. A successful response already contains each shipment's airwayBill.
  • 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.

OrderShipment
ID formatFSO-YYMMDD-XXXXXXSHP-YYMMDD-XXXXXX
What it representsOne checkout: everything you book and pay for togetherOne parcel carried by one courier service
PaidOnce, for all its shipmentsIts priceDetail.totalPrice is part of the order payment
Has an airway billNoYes, airwayBill and trackingUrl once booked
Status to watchRarely neededYes: delivery progress lives here
CancelcancelOrder cancels all its shipmentscancelShipment 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.

  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

StepWhat Shipping Engine doesIf it fails
1. ValidateChecks 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. CreateSaves the order (DRAFT) and one shipment per rate (WAITING_FOR_PAYMENT).—
3. PayDeducts 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 courierSends 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. RespondReturns 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 statusWhen you see it
DRAFTCreated, but payment or courier booking failed. Nothing is charged.
CONFIRMEDPaid and sent to the couriers. This is what a successful POST /b2b/orders returns.
CANCELLEDYou 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.

Main path
WAITING_FOR_PAYMENTOrder created, not paid yet
CONFIRMEDPaid, courier being booked
PENDING_PICKUPWaiting for the courier to collectorPENDING_DROPOFFWaiting for you to drop it off
IN_TRANSITOn its way
DELIVEREDReceived by the receiver
Before pickup
CANCELLEDCancelled and refunded
During delivery
PROBLEM_SHIPMENTCourier reported a problemback on track, delivered, or returned
Return to sender
RTS_CONFIRMEDReturn to sender startedRTS_TRANSITOn its way backRTS_DELIVEREDBack with the senderRTS_PROBLEM_SHIPMENTProblem on the way backcan happen on the way back, then continues
WaitingOn its wayDeliveredCancelledNeeds attentionReturn Final: never changes again
Hover a status to see what it means. Statuses only move forward; final ones never change.

Rules that always hold:

  • DELIVERED and RTS_DELIVERED are final. Nothing changes them.
  • Once a shipment enters the return branch (RTS_*), it never goes back to the normal path or to CANCELLED.
  • A failed pickup attempt that the courier will retry keeps the shipment in PENDING_PICKUP.
  • WAITING_FOR_PAYMENT and CONFIRMED last only for the duration of the POST /b2b/orders call when it succeeds.

Status table

statusMeaningTerminal?Can cancel?Webhook eventWhat to do
WAITING_FOR_PAYMENTCreated, not paid. Seen on orders whose payment failed.NoYes, nothing to refund—Create a new order, or cancel this one.
CONFIRMEDPaid, courier not booked yet.NoYes, refunded—Wait. Booking happens within the same request.
PENDING_PICKUPBooked. Waiting for the courier to collect the parcel from the sender.NoYes, courier is asked firstshipment.dispatched when booked, then shipment.pending_pickup (also when a driver is assigned)Have the parcel packed and labelled with the AWB.
PENDING_DROPOFFBooked. Waiting for you to drop the parcel at a courier counter.NoYes, courier is asked firstshipment.dispatchedDrop the parcel off and show the AWB.
IN_TRANSITThe courier has the parcel.NoRequest only: most couriers refuse after pickupshipment.in_transitShare trackingUrl with your customer.
PROBLEM_SHIPMENTThe courier reported a problem: failed delivery, damage, loss, or an instant pickup that failed or expired.NoRequest onlyshipment.problem_detected, or shipment.pickup_failed for a failed instant pickupRead the latest history entry. Contact support if it doesn't move on.
DELIVEREDThe receiver has the parcel.YesNoshipment.deliveredDone. For COD, see Balance and charges.
CANCELLEDCancelled by you, by the courier, or because booking was rejected.YesAlready cancelled (returns success)shipment.cancelledCheck the refund in your balance logs.
RTS_CONFIRMEDThe courier is returning the parcel to the sender.NoNoshipment.rts_confirmedContact the receiver. See Returns (RTS).
RTS_TRANSITThe parcel is on its way back.NoNoshipment.rts_transitPrepare to receive it.
RTS_PROBLEM_SHIPMENTA problem on the way back.NoNoshipment.rts_problem_shipmentContact support.
RTS_DELIVEREDThe parcel is back with the sender.YesNoshipment.rts_delivered, and shipment.rts_billed if a return fee appliesCheck 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 causeWhat usually happens next
Receiver not home, wrong or incomplete addressThe courier retries, or starts a return.
Parcel damaged or lostThe 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.

SourceWhenNotes
Courier updatesAs soon as the courier reports an eventMost changes arrive this way.
Periodic checksOn a schedule, for shipments that are not final yetCatches events a courier didn't push.
On-demand trackingWhen you call trackShipmentFetches 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.

histories (from retrieveShipment)
[
  { "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" }
]
WhereWhat you get
retrieveShipmenthistories[] with status, description, timestamp, plus driverDetails for instant couriers
trackShipmentcurrentStatus 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?

On this page