Plan your integration
Decide what to build, which features you need, and what to prepare before you write code.
- Product
- APIShipping Engine API
- Section
- Get started
- Reading time
- 5 min read
In short
- Every integration follows the same four steps: find regions, get rates, create an order, track.
- You choose how far to go: show rates at checkout only, or also book, track and cancel shipments.
- Before you start you need an approved business verification, an API key and, for booking, a funded balance.
What you can build
Most integrations fall into one of these shapes. Pick the one closest to yours, then read the pages it lists.
| You want to… | You use | Start with |
|---|---|---|
| Show shipping prices at checkout | Regions and rates only. Nothing is booked or charged. | Checkout options |
| Book regular shipments (JNE, J&T, SPX…) | Regions, rates, orders, tracking, webhooks | Book a shipment |
| Collect cash on delivery (COD) | Everything above, with codOption on the rate | Ship with COD |
| Send same-day parcels with a driver (Lalamove, Grab, Paxel, Dash…) | Everything above, with a vehicle and coordinates | Book an instant courier |
You can start small. A checkout-only integration uses the same rate calls you later need for booking, so nothing is wasted when you add orders.
The four steps
- 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
- 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
| Step | Call | What you get |
|---|---|---|
| 1. Find regions | GET /b2b/region/find | A subdistrictId for each address. Look it up once and store it. |
| 2. Get rates | POST /b2b/shipping-rate | One priced quote per courier service, each with a shippingRateCode. |
| 3. Create an order | POST /b2b/orders | The shipment is paid from your balance and booked with the courier. You get an airway bill. |
| 4. Track | Webhooks, or GET /b2b/shipments/{code}/details | Status updates until the shipment is delivered, cancelled or returned. |
Read How shipping rates work and Order and shipment lifecycle before you design your data model. They explain what a rate locks in and which statuses you will see.
Webhooks or polling
You learn about status changes in one of two ways. Use webhooks as your main source, and polling as a backup.
| Webhooks | Polling | |
|---|---|---|
| How | Shipping Engine sends a POST to your HTTPS endpoint on each change. | You call GET /b2b/shipments or GET /b2b/shipments/{code}/details on a schedule. |
| Speed | Near real time. | As often as you poll. |
| Setup | A public HTTPS endpoint, signature verification, one-time registration. | None beyond your API key. |
| Limits | Retried for a short time only. No ordering guarantee. Events can be missed if your endpoint is down for long. | More API calls. You still need to compare statuses yourself. |
| Best for | Updating your customers quickly. | Daily reconciliation, catching anything a webhook missed. |
A common pattern: react to webhooks, and once a day list shipments that are not yet final and refresh them. See Webhooks and Track shipments.
Decisions to make up front
- Which couriers? All regular couriers (
REGULAR), instant couriers (INSTANT), or a fixed list. See Couriers and services. - How do customers enter addresses? Region search behind an autocomplete, a postal code field, or province → city → district → subdistrict menus. See Regions.
- Pickup or drop-off? Pickup needs the sender's coordinates for regular couriers. Drop-off means you take the parcel to a courier counter.
- Insurance? Required choice (
trueorfalse) for regular couriers. See Insurance and COD. - COD? Needs the
USE_CODpermission, and an order can't mix COD and non-COD shipments. - One order or many? An order can hold several shipments, paid together. See Multi-shipment orders.
- How will you track? Webhooks, polling, or both.
- How will you handle failures? Expired rates, insufficient balance, and timeouts on order creation. See Handle errors and retries.
- Who watches the balance? When it runs out, orders fail with 400
Payment failed, but order '…' was created successfully. Reason: Insufficient balance.. See Balance and charges.
What you need before you start
| You need | Why | How to get it |
|---|---|---|
| A Fastrac account | To use the dashboard and request verification. | Sign up in the dashboard at app.fastrac.cc. |
| Approved business verification (KYC) | API keys, COD and webhooks are unlocked after approval. | Submit your business details in the dashboard. |
| An API key | To get access tokens. You receive a production secret and a sandbox secret. | Issued when verification is approved. See API credentials. |
| Balance (production) | Each non-COD shipment is paid from your balance when you create the order. | Top up in the dashboard. There is no top-up API. |
| A public HTTPS endpoint (optional) | To receive webhooks. | Your own server. See Webhooks. |
Next steps
Was this page helpful?