Skip to Content
FastracDocs

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 CREDIT or DEBIT entry.

The four pockets

Your balance is split into four pockets. GET /b2b/user-balance returns all of them, in whole Rupiah.

PocketFieldWhat it's forHow it fills upWithdrawable?
Shipping credit (saldo)shippingCreditPaying for shipments. API orders always use this pocket.Top-ups in the dashboard, refunds, transfers from payoutNo
Payout balancepayoutBalanceMoney that belongs to you: COD proceeds, refunds of orders paid by QRIS or payoutCOD settlement, refunds, referral transfersYes, to your bank account
Referral balancereferralBalanceReferral commissions1% of the paid amount of each delivered shipment from users you referredTransfer to payout first
PointspointDashboard rewardsDashboard featuresNo
InboundResponse
{
  "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

MomentWhat happens
You create an orderThe totalPrice of every non-COD shipment is deducted from shipping credit, all at once. COD orders deduct nothing upfront.
A shipment is cancelledThe amount paid for it goes back to the pocket that paid. See Cancellations and refunds.
The courier reweighs the parcel and the price goes upThe difference is charged. See Adjustments.
A parcel is returned to the senderSome couriers charge a return fee. See Returns (RTS).
A COD shipment is deliveredThe COD proceeds are settled to your balance.
A COD shipment is cancelled or returnedCOD 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.

TriggerPocketTypeLog description patternWebhook
Order paid (one entry per non-COD shipment)Shipping creditDEBITPayment for order <order> shipment <shipment>— (the 201 response)
Courier booking failed during order creationShipping creditCREDITRefund 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 creditCREDITCancel 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 cancelledPayout balanceDEBITCancel shipment <shipment> for order <order> (COD reversal)shipment.cancelled
Price increase after reweighShipping credit, else payoutDEBITStarts with the courier name, for example SPX price adjustment | … or Lion price adj(…) <shipment>shipment.price_changed
Return feeShipping credit, else payoutDEBITTagihan retur (RTS) resi <awb>shipment.rts_billed
COD shipment returnedPayout balanceDEBITRTS shipment <shipment> for order <order> (COD reversal)shipment.rts_delivered
COD shipment deliveredPayout balance and shipping creditCREDIT / DEBITMentions COD and <order>shipment.delivered
Unpaid adjustment or return fee settled laterShipping credit or payoutDEBITPembayaran … resi <awb>—
Top-up (dashboard)Shipping creditCREDITTop-up description—
Transfer payout → shipping credit (dashboard)Payout, then shipping creditDEBIT + CREDITTransfer payout to credit (…) / Transfer from payout (…)—
Withdrawal (dashboard)Payout balanceDEBITYour withdrawal note—
Rejected withdrawalPayout balanceCREDITRefund for rejected withdrawal request #…—
Referral commissionReferral balanceCREDITReferral 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

SituationWhat happensWhat to do
Creating an orderRejected 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 feeShipping 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

CallUse it to
GET /b2b/user-balanceCheck the pockets before a batch of orders, or alert when shipping credit runs low.
GET /b2b/user-balance/logsList movements, newest first, to reconcile.

Filters for the logs:

QueryMeaning
typeCREDIT or DEBIT
startDate, endDateISO 8601 date range
shipmentIdText search in the description, for example a shipment code or airway bill
limit, cursorPage 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"
InboundResponse
{
  "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?

On this page