Reconcile your balance
Read your balance and its logs, match every charge and refund to a shipment, and catch extra charges daily.
- Product
- APIShipping Engine API
- Section
- Guides
- Reading time
- 6 min read
Goal: know where every rupiah of your balance went: which shipment each charge belongs to, which refunds came back, and which extra charges (reweighs, return fees) appeared.
Before you start:
- You can get an access token. See the Quickstart.
- You store the order code (
FSO-…), shipment code (SHP-…), shipmentidand airway bill of every booking. See Book a shipment. - You know how charges work. See Balance and charges.
Read your current balance
GET /b2b/user-balancereturns every pocket, in IDR:curl -s "$FASTRAC_API/b2b/user-balance" -H "Authorization: Bearer $FASTRAC_TOKEN"InboundResponse { "statusCode": 200, "message": "Request successful.", "data": { "balance": { "point": 0, "shippingCredit": 1250000, "payoutBalance": 480000, "referralBalance": 0 }, "timestamp": "2026-11-20T17:00:00.000Z" } }Pocket What it holds shippingCreditYour top-ups. Bookings are paid from here. payoutBalanceCOD proceeds and some refunds. You can withdraw it from the dashboard. referralBalanceReferral earnings. pointPoints. Top-ups and withdrawals are done in the dashboard, not through the API.
List the balance logs
Every movement in any pocket is a log entry.
GET /b2b/user-balance/logslists them, newest first.Query Meaning typeCREDIT(money in) orDEBIT(money out).startDate,endDateFilter on when the entry was created. ISO 8601 with offset, for example 2026-11-20T00:00:00+07:00.shipmentIdA text search in the description (up to 50 characters, case-insensitive). Pass a shipment code, order code or airway bill. limitPage size. Default 25, maximum 100. cursorThe nextCursorof the previous page.curl -s -G "$FASTRAC_API/b2b/user-balance/logs" \ -H "Authorization: Bearer $FASTRAC_TOKEN" \ --data-urlencode "shipmentId=SHP-261120-D4E5F6"InboundResponse { "statusCode": 200, "message": "Request successful.", "data": { "logs": [ { "id": 5521, "userId": 812, "type": "CREDIT", "amount": 9099, "description": "Cancel shipment SHP-261120-D4E5F6 for order FSO-261120-A1B2C3 (wallet refund)", "createdAt": "2026-11-20T06:40:11.000Z", "cursor": "NTUyMQ==" }, { "id": 5498, "userId": 812, "type": "DEBIT", "amount": 9099, "description": "Payment for order FSO-261120-A1B2C3 shipment SHP-261120-D4E5F6", "createdAt": "2026-11-20T03:12:44.000Z", "cursor": "NTQ5OA==" } ], "nextCursor": null } }amountis always positive;typegives the direction. An entry doesn't say which pocket it touched, so read the description.Match entries to shipments
Descriptions are written for people, but they contain the codes you need. These are the common ones:
Type Description looks like Meaning Match on DEBITPayment for order FSO-… shipment SHP-…Booking charge, one per non-COD shipment. Shipment code CREDITCancel shipment SHP-… for order FSO-… (wallet refund)Refund of a cancelled shipment. Shipment code CREDITRefund due to dispatch failure for order FSO-…Refund after a booking that failed. Order code DEBITTagihan retur (RTS) resi <AWB>Return fee. Airway bill DEBIT<Courier> price adjustment | Order #<id> | Shipment #<id> | +<amount>Extra charge after the courier reweighed the parcel. Shipment id(the number fromGET /b2b/shipments)DEBITPembayaran selisih ongkir resi <AWB>A price difference collected later. Airway bill DEBIT… (COD reversal)A COD amount taken back after a cancellation or return. Shipment code Match codes, not whole sentences
The wording of descriptions can change. Extract the codes (
SHP-…,FSO-…, airway bills,Shipment #…) with a pattern and match on those. Put anything you can't match on a list for a person to check.Run a daily reconciliation
Once a day (for example at 01:00 WIB), fetch yesterday's logs and compare them with your bookings:
reconcile.js const API = process.env.FASTRAC_API; async function fetchLogs(startDate, endDate, token) { const logs = []; let cursor; do { const qs = new URLSearchParams({ startDate, endDate, limit: '100', ...(cursor && { cursor }) }); const res = await fetch(`${API}/b2b/user-balance/logs?${qs}`, { headers: { Authorization: `Bearer ${token}` } }); if (!res.ok) throw new Error((await res.json()).message); const { data } = await res.json(); logs.push(...data.logs); cursor = data.nextCursor; } while (cursor); return logs; } function classify(log) { const d = log.description; const shipmentCode = d.match(/SHP-\d{6}-[A-Z0-9]+/)?.[0]; const orderCode = d.match(/FSO-\d{6}-[A-Z0-9]+/)?.[0]; if (d.startsWith('Payment for order')) return { kind: 'booking', shipmentCode, orderCode }; if (d.includes('(wallet refund)')) return { kind: 'refund', shipmentCode, orderCode }; if (d.startsWith('Refund due to dispatch failure')) return { kind: 'failed-booking-refund', orderCode }; if (d.includes('(COD reversal)')) return { kind: 'cod-reversal', shipmentCode, orderCode }; if (d.startsWith('Tagihan retur')) return { kind: 'return-fee', awb: d.split('resi ')[1] }; if (/price adjustment/i.test(d)) return { kind: 'reweigh', shipmentId: d.match(/Shipment #(\d+)/)?.[1] }; if (d.startsWith('Pembayaran selisih')) return { kind: 'price-difference', awb: d.split('resi ')[1] }; return { kind: 'other' }; } const logs = await fetchLogs('2026-11-19T00:00:00+07:00', '2026-11-19T23:59:59.999+07:00', token); for (const log of logs) { const entry = { ...log, ...classify(log) }; await db.balanceEntries.upsert({ logId: log.id }, entry); // log.id is unique: safe to re-run }Then check, for that day:
- Every non-COD shipment you booked has exactly one
bookingdebit, equal to itspriceDetail.totalPrice. - Every shipment you cancelled has one
refundcredit of the same amount. - Every
return-fee,reweighandprice-differenceentry is linked to a shipment and passed on to whoever pays for it (your margin, or the customer). - Every
otherentry is a top-up, withdrawal or transfer you recognise from the dashboard.
Save
GET /b2b/user-balanceonce a day too, so you can see the balance trend next to the entries.- Every non-COD shipment you booked has exactly one
Webhooks that announce extra charges
Extra charges arrive after delivery events, sometimes days later. These webhooks tell you when they happen, so you don't have to wait for the daily run:
| Event | Fields in data | Meaning |
|---|---|---|
shipment.price_changed | price_before, price_after, delta, payment_status | The courier charged more for the shipment (usually after reweighing). The difference is deducted. |
shipment.measurement_changed | measurement_before, measurement_after | The courier measured a different weight or size. A price_changed may follow. |
shipment.rts_billed | rts_fee, payment_status | A return fee was billed. |
When payment_status is failed, your balance didn't cover the charge. Top up your shipping credit;
Fastrac support follows up on the unpaid amount. Price decreases are not refunded. See
Adjustments.
Checklist
- Fetch yesterday's logs every day, following
nextCursor, and store them byid. - Extract shipment codes, order codes, airway bills and shipment ids from descriptions.
- Check one booking debit per non-COD shipment and one refund per cancelled shipment.
- Route return fees and reweigh charges to the right shipment.
- Subscribe to
shipment.price_changedandshipment.rts_billed, and top up whenpayment_statusisfailed.
Was this page helpful?