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 toPOST /b2b/orders. - A rate expires at
validUntil, usually about 15 minutes after you request it. After that, ask for a new one.
- 1subdistrictId
YouShipping Engine
Find the region
Turn each address into the ID of its subdistrict.
GET/b2b/region/find
- 2shippingRateCodeYou are here
YouShipping Engine
Get rates
Describe the parcel and route. Get a price from every courier.
POST/b2b/shipping-rate
- 3airwayBill
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
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 rate | So when you create the order… |
|---|---|
Courier and service (courierCode, serviceName) | you don't send them again |
| Origin and destination addresses | you only add names and phone numbers |
| Parcel weight, size and declared value | the parcel can't change without a new quote |
| Insurance and COD choices | they 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.
| Situation | What happens |
|---|---|
You create an order before validUntil | The shipment is booked at the quoted price. |
You create an order after validUntil | The 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 expiry | You 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:
courierCode | Asks | If one courier fails |
|---|---|---|
JNE, JNT, SPX, LALAMOVE, … | That courier only | You get the error |
REGULAR | Every regular (non-instant) courier | It is skipped and the others are returned |
INSTANT | Every instant courier | It is skipped and the others are returned |
ALL | Every courier | It 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
| Code | Courier | Type |
|---|---|---|
JNE | JNE | Regular |
JNT | J&T Express | Regular |
SPX | SPX (Shopee Express) | Regular |
SAP | SAP Express | Regular |
NINJA | Ninja Xpress | Regular |
IDX | ID Express | Regular |
ANTERAJA | Anteraja | Regular |
LION | Lion Parcel | Regular |
BLITZ | Blitz | Instant |
PAXEL | Paxel | Instant, needs vehicle |
LALAMOVE | Lalamove | Instant, needs vehicle |
GRAB | GrabExpress | Instant, needs vehicle |
DASH | Dash | Instant, needs vehicle |
Service types
Each rate has a serviceType, which tells you the speed class:
serviceType | Typical delivery | Notes |
|---|---|---|
INSTANT | Within hours, same city | Courier picks up with a bike or car. |
SAMEDAY | Same day | Usually within one city. |
NEXTDAY | Next day | |
REGULAR | 1–7 days | Most common for e-commerce. |
CARGO | Several days | Heavy 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:
Set vehicle, for example BIKE or CAR. The parcel must fit the vehicle's weight and size
limits. Larger parcels need a bigger vehicle.
Instant couriers price by distance, so send coordinate (latitude and longitude) for the origin
and every destination. Without them the courier can only guess from the subdistrict.
insurance is required for regular couriers but optional for PAXEL, LALAMOVE, GRAB and DASH.
If you send scheduledAt, Lalamove, Dash and Blitz price that pickup time. When you create the order,
use the same schedule, or none. A different time is rejected with PICKUP_SCHEDULE_NOT_QUOTED, so
quote again for the new time.
Multi-stop trips are available with Lalamove. Send several destinations, each with a unique
stopOrder (1, 2, 3…), and the driver visits them in that order. Other couriers carry one
destination per shipment, so book one shipment per address instead. See
Multi-shipment and multi-stop orders.
Anatomy of a rate
| Field | Meaning |
|---|---|
shippingRateCode | The quote ID. Pass it to POST /b2b/orders. |
validUntil | When the quote expires (UTC). |
courierCode, serviceName, serviceType | Who carries it and how fast. |
etdRange | Estimated delivery, as text. |
isSupportCod | The service can collect cash on delivery. |
isSupportPickup, isSupportDropOff | Whether the courier collects the parcel, or you drop it at a counter. |
priceDetail | The full price breakdown. See Pricing. |
dimension | The parcel that was priced. With several packages, this is the combined parcel. |
origin, destinations[] | The addresses, as quoted. |
destinations[].packages[].packageCode | Use 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?