Skip to Content
FastracDocs

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 useStart with
Show shipping prices at checkoutRegions and rates only. Nothing is booked or charged.Checkout options
Book regular shipments (JNE, J&T, SPX…)Regions, rates, orders, tracking, webhooksBook a shipment
Collect cash on delivery (COD)Everything above, with codOption on the rateShip with COD
Send same-day parcels with a driver (Lalamove, Grab, Paxel, Dash…)Everything above, with a vehicle and coordinatesBook 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

  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

    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

StepCallWhat you get
1. Find regionsGET /b2b/region/findA subdistrictId for each address. Look it up once and store it.
2. Get ratesPOST /b2b/shipping-rateOne priced quote per courier service, each with a shippingRateCode.
3. Create an orderPOST /b2b/ordersThe shipment is paid from your balance and booked with the courier. You get an airway bill.
4. TrackWebhooks, or GET /b2b/shipments/{code}/detailsStatus 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.

WebhooksPolling
HowShipping 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.
SpeedNear real time.As often as you poll.
SetupA public HTTPS endpoint, signature verification, one-time registration.None beyond your API key.
LimitsRetried 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 forUpdating 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 (true or false) for regular couriers. See Insurance and COD.
  • COD? Needs the USE_COD permission, 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 needWhyHow to get it
A Fastrac accountTo 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 keyTo 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?

On this page