Balance and charges
The four balance pockets, every event that moves money, and how to read your balance and logs through the API.
- Product
- APIShipping Engine API
- Section
- Core concepts
- Reading time
- 7 min read
In short
- Shipping is prepaid. Orders are paid from your shipping credit the moment you create them.
- Refunds go back to the pocket that paid. Later charges (price adjustments, return fees) come from shipping credit first, then payout balance.
- You top up in the dashboard. Through the API you can read the balance and its logs, where every movement is a
CREDITorDEBITentry.
The four pockets
Your balance is split into four pockets. GET /b2b/user-balance
returns all of them, in whole Rupiah.
| Field | What it's for | How it fills up | Withdrawable? | |
|---|---|---|---|---|
| Shipping credit (saldo) | shippingCredit | Paying for shipments. API orders always use this pocket. | Top-ups in the dashboard, refunds, transfers from payout | No |
| Payout balance | payoutBalance | Money that belongs to you: COD proceeds, refunds of orders paid by QRIS or payout | COD settlement, refunds, referral transfers | Yes, to your bank account |
| Referral balance | referralBalance | Referral commissions | 1% of the paid amount of each delivered shipment from users you referred | Transfer to payout first |
| Points | point | Dashboard rewards | Dashboard features | No |
{
"statusCode": 200,
"message": "Request successful.",
"data": {
"balance": { "point": 0, "shippingCredit": 1250000, "payoutBalance": 340000, "referralBalance": 0 },
"timestamp": "2026-11-20T10:15:00.000Z"
}
}When money moves
| Moment | What happens |
|---|---|
| You create an order | The totalPrice of every non-COD shipment is deducted from shipping credit, all at once. COD orders deduct nothing upfront. |
| A shipment is cancelled | The amount paid for it goes back to the pocket that paid. See Cancellations and refunds. |
| The courier reweighs the parcel and the price goes up | The difference is charged. See Adjustments. |
| A parcel is returned to the sender | Some couriers charge a return fee. See Returns (RTS). |
| A COD shipment is delivered | The COD proceeds are settled to your balance. |
| A COD shipment is cancelled or returned | COD proceeds already credited for it are reversed. |
Every movement
Each movement writes one balance log entry. Use the description to match it to an order or shipment.
<order> is an order code (FSO-…), <shipment> a shipment code (SHP-…), <awb> an airway bill.
| Trigger | Type | Log description pattern | Webhook | |
|---|---|---|---|---|
| Order paid (one entry per non-COD shipment) | Shipping credit | DEBIT | Payment for order <order> shipment <shipment> | — (the 201 response) |
| Courier booking failed during order creation | Shipping credit | CREDIT | Refund due to dispatch failure for order <order> | — (the 400 response) |
| Shipment cancelled (by you, the courier, or a rejected booking) | Pocket that paid: usually shipping credit | CREDIT | Cancel shipment <shipment> for order <order> (wallet refund). Orders paid by payout or QRIS in the dashboard end in (payout refund), points in (point refund). | shipment.cancelled |
| COD shipment cancelled | Payout balance | DEBIT | Cancel shipment <shipment> for order <order> (COD reversal) | shipment.cancelled |
| Price increase after reweigh | Shipping credit, else payout | DEBIT | Starts with the courier name, for example SPX price adjustment | … or Lion price adj(…) <shipment> | shipment.price_changed |
| Return fee | Shipping credit, else payout | DEBIT | Tagihan retur (RTS) resi <awb> | shipment.rts_billed |
| COD shipment returned | Payout balance | DEBIT | RTS shipment <shipment> for order <order> (COD reversal) | shipment.rts_delivered |
| COD shipment delivered | Payout balance and shipping credit | CREDIT / DEBIT | Mentions COD and <order> | shipment.delivered |
| Unpaid adjustment or return fee settled later | Shipping credit or payout | DEBIT | Pembayaran … resi <awb> | — |
| Top-up (dashboard) | Shipping credit | CREDIT | Top-up description | — |
| Transfer payout → shipping credit (dashboard) | Payout, then shipping credit | DEBIT + CREDIT | Transfer payout to credit (…) / Transfer from payout (…) | — |
| Withdrawal (dashboard) | Payout balance | DEBIT | Your withdrawal note | — |
| Rejected withdrawal | Payout balance | CREDIT | Refund for rejected withdrawal request #… | — |
| Referral commission | Referral balance | CREDIT | Referral commission from shipment <shipment> | — |
Logs don't name the pocket
A log entry has type, amount, description and createdAt, but no pocket field. Read the
pocket from the description, and compare the balance before and after when you reconcile.
Insufficient balance
| Situation | What happens | What to do |
|---|---|---|
| Creating an order | Rejected with 400 Payment failed, but order 'FSO-…' was created successfully. Reason: Insufficient balance. Nothing is charged and no courier is booked. The order stays DRAFT. | Top up, then create a new order. |
| Price adjustment or return fee | Shipping Engine tries shipping credit, then payout balance. If neither covers the full amount, the charge is recorded as unpaid and the webhook has payment_status: "failed". | Top up. Fastrac support contacts you to settle it. |
Keep a buffer
An order is all-or-nothing: if the balance can't cover every non-COD shipment, none is booked. Keep enough shipping credit for your peak hour, plus room for adjustments and return fees.
Topping up
There is no top-up endpoint. Top up in the Fastrac dashboard: open Balance and choose a manual top-up or QRIS. You can also move funds from your payout balance to your shipping credit there.
Reading balance and logs through the API
| Call | Use it to |
|---|---|
GET /b2b/user-balance | Check the pockets before a batch of orders, or alert when shipping credit runs low. |
GET /b2b/user-balance/logs | List movements, newest first, to reconcile. |
Filters for the logs:
| Query | Meaning |
|---|---|
type | CREDIT or DEBIT |
startDate, endDate | ISO 8601 date range |
shipmentId | Text search in the description, for example a shipment code or airway bill |
limit, cursor | Page size and the nextCursor from the previous page |
curl "https://sandbox-api.fastrac.example/b2b/user-balance/logs?type=DEBIT&shipmentId=SHP-261120-K7M2QX&limit=25" \
-H "Authorization: Bearer $TOKEN"{
"statusCode": 200,
"message": "Request successful.",
"data": {
"logs": [
{
"id": 98231,
"userId": 412,
"type": "DEBIT",
"amount": 12984,
"description": "Payment for order FSO-261120-B4TQ9P shipment SHP-261120-K7M2QX",
"createdAt": "2026-11-20T03:12:44.000Z",
"cursor": "eyJpZCI6OTgyMzF9"
}
],
"nextCursor": null
}
}For a step-by-step reconciliation, see Reconcile your balance.
Common mistakes
Expecting a refund when the price goes down
Only price increases are charged after pickup. If the courier's final price is lower, nothing is refunded. See Adjustments.
Counting the order total as your final cost
The amount paid at order time can grow later through adjustments and return fees. Reconcile with the balance logs, not just the order response.
Expecting the payout balance to pay for orders
API orders are paid from shipping credit only. Money in your payout balance is not used for new orders until you transfer it to shipping credit in the dashboard.
Was this page helpful?