Skip to Content
FastracDocs

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-…), shipment id and airway bill of every booking. See Book a shipment.
  • You know how charges work. See Balance and charges.
  1. Read your current balance

    GET /b2b/user-balance returns 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"
      }
    }
    PocketWhat 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.

  2. List the balance logs

    Every movement in any pocket is a log entry. GET /b2b/user-balance/logs lists them, newest first.

    QueryMeaning
    typeCREDIT (money in) or DEBIT (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 nextCursor of 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
      }
    }

    amount is always positive; type gives the direction. An entry doesn't say which pocket it touched, so read the description.

  3. Match entries to shipments

    Descriptions are written for people, but they contain the codes you need. These are the common ones:

    TypeDescription looks likeMeaningMatch 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 from GET /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.

  4. 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:

    1. Every non-COD shipment you booked has exactly one booking debit, equal to its priceDetail.totalPrice.
    2. Every shipment you cancelled has one refund credit of the same amount.
    3. Every return-fee, reweigh and price-difference entry is linked to a shipment and passed on to whoever pays for it (your margin, or the customer).
    4. Every other entry is a top-up, withdrawal or transfer you recognise from the dashboard.

    Save GET /b2b/user-balance once a day too, so you can see the balance trend next to the entries.

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:

EventFields in dataMeaning
shipment.price_changedprice_before, price_after, delta, payment_statusThe courier charged more for the shipment (usually after reweighing). The difference is deducted.
shipment.measurement_changedmeasurement_before, measurement_afterThe courier measured a different weight or size. A price_changed may follow.
shipment.rts_billedrts_fee, payment_statusA 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 by id.
  • 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_changed and shipment.rts_billed, and top up when payment_status is failed.

Was this page helpful?

On this page