Skip to Content
FastracDocs
Shipping rates

How shipping rates work

What a rate is, how long it lasts, how to pick couriers, and what it locks in.

Product
APIShipping Engine API
Section
Shipping rates
Reading time
6 min read

In short

  • A shipping rate is a priced quote for one courier service, route and parcel.
  • Every rate has a shippingRateCode. You book a shipment by passing that code to POST /b2b/orders.
  • A rate expires at validUntil, usually about 15 minutes after you request it. After that, ask for a new one.
  1. 1subdistrictId

    YouShipping Engine

    Find the region

    Turn each address into the ID of its subdistrict.

    GET/b2b/region/find

  2. 2shippingRateCode
    You are here

    YouShipping Engine

    Get rates

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

    POST/b2b/shipping-rate

  3. 3airwayBill

    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

What a rate is

When you call POST /b2b/shipping-rate, Shipping Engine asks the couriers for a price, adds discounts, insurance and tax, and saves each result as a rate. The response is a list of these rates.

A rate is not just a number. It locks in everything the courier priced:

Locked in by the rateSo when you create the order…
Courier and service (courierCode, serviceName)you don't send them again
Origin and destination addressesyou only add names and phone numbers
Parcel weight, size and declared valuethe parcel can't change without a new quote
Insurance and COD choicesthey are already priced in
The price (priceDetail.totalPrice)this is the amount deducted from your balance

Changing anything means a new quote

If the customer edits the address, adds an item, or turns insurance on, request a new rate. Don't reuse an old shippingRateCode for a different parcel. The courier priced the old one.

How long a rate lasts

Each rate has a validUntil timestamp. Its lifetime is set per courier service and is typically 15 minutes.

SituationWhat happens
You create an order before validUntilThe shipment is booked at the quoted price.
You create an order after validUntilThe order is rejected with Shipping rate code '…' have expired. Request a new rate and show the new price.
You call GET /b2b/shipping-rate/{code} after expiryYou still get the rate back, for display or auditing. It just can't be booked.

Tip

Quote when the customer reaches the shipping step, not when they open the product page. Then the rate is still valid when they pay.

Choosing couriers

courierCode controls how many couriers you ask:

courierCodeAsksIf one courier fails
JNE, JNT, SPX, LALAMOVE, …That courier onlyYou get the error
REGULAREvery regular (non-instant) courierIt is skipped and the others are returned
INSTANTEvery instant courierIt is skipped and the others are returned
ALLEvery courierIt is skipped and the others are returned

If no courier at all can carry the parcel, you get 404 with No shipping rates available for the requested route or parameters. Treat it as "no shipping options", not as a server error.

Courier codes

CodeCourierType
JNEJNERegular
JNTJ&T ExpressRegular
SPXSPX (Shopee Express)Regular
SAPSAP ExpressRegular
NINJANinja XpressRegular
IDXID ExpressRegular
ANTERAJAAnterajaRegular
LIONLion ParcelRegular
BLITZBlitzInstant
PAXELPaxelInstant, needs vehicle
LALAMOVELalamoveInstant, needs vehicle
GRABGrabExpressInstant, needs vehicle
DASHDashInstant, needs vehicle

Service types

Each rate has a serviceType, which tells you the speed class:

serviceTypeTypical deliveryNotes
INSTANTWithin hours, same cityCourier picks up with a bike or car.
SAMEDAYSame dayUsually within one city.
NEXTDAYNext day
REGULAR1–7 daysMost common for e-commerce.
CARGOSeveral daysHeavy or bulky parcels, cheaper per kg.

etdRange gives the courier's estimate as display text, for example 2 - 3 Days. It is an estimate, not a promise.

Instant couriers

Instant couriers (PAXEL, LALAMOVE, GRAB, DASH, or courierCode: "INSTANT") work a little differently:

Anatomy of a rate

FieldMeaning
shippingRateCodeThe quote ID. Pass it to POST /b2b/orders.
validUntilWhen the quote expires (UTC).
courierCode, serviceName, serviceTypeWho carries it and how fast.
etdRangeEstimated delivery, as text.
isSupportCodThe service can collect cash on delivery.
isSupportPickup, isSupportDropOffWhether the courier collects the parcel, or you drop it at a counter.
priceDetailThe full price breakdown. See Pricing.
dimensionThe parcel that was priced. With several packages, this is the combined parcel.
origin, destinations[]The addresses, as quoted.
destinations[].packages[].packageCodeUse it as shippingRatePackageCode when you create the order.

Common mistakes

Weight in kilograms

weight is in grams. Sending 1.2 for a 1.2 kg parcel quotes a 1-gram parcel. The courier reweighs it and charges you the difference later.

Leaving out insurance

For regular couriers, insurance must be true or false. Leaving it out returns insurance parameter is required for regular shipments.

Booleans as strings

Send "isGlassware": false, not "false". A string is read as true.

Was this page helpful?

On this page