Balances

Your balance represents the cumulative state of all funds flowing through your Commerce account. Unlike individual transactions which show moment-to-moment activity, your balance aggregates everything into a single view: what money is available for payout, what's still pending settlement, what's reserved for refunds, and what's already been paid out. This endpoint gives you the financial snapshot you need for dashboards, accounting reconciliation, and cash flow planning.

The Balance object

Balances are computed from periodic snapshots that aggregate all balance transactions up to a specific cutoff time. Each balance breaks down by currency and tracks funds across four states: available (ready for payout), pending (recognized but not yet settled), reserved (held for potential refunds), and refund (funds returned to customers). The includes_transactions_before timestamp tells you the cutoff for the snapshot—transactions created after that time aren't included in these numbers.

Properties

ghsobjectBalance breakdown for Ghanaian Cedis. Shows funds in different states and the snapshot cutoff time.Click or tap to expand
- Name
  available
  Type
  object
  Description
  Funds that have settled and are ready for payout. These can be included in the next payout execution.
  View available attributesClick or tap to expand
  Name
  amount
  Type
  integer
  Description
  Available amount in minor units (pesewas for GHS).
- Name
  pending
  Type
  object
  Description
  Funds recognized but not yet settled—typically aging through the settlement window (usually 7 days).
  View pending attributesClick or tap to expand
  Name
  amount
  Type
  integer
  Description
  Pending amount in minor units (pesewas for GHS).
- Name
  reserved
  Type
  object
  Description
  Funds automatically held by Commerce for potential disputes, chargebacks, or fraud protection. Platform-managed reserves not available for payout.
  View reserved attributesClick or tap to expand
  Name
  amount
  Type
  integer
  Description
  Reserved amount in minor units (pesewas for GHS).
- Name
  refund
  Type
  object
  Description
  Funds you've set aside for processing customer refunds. This is your refund buffer—money earmarked for handling returns and cancellations.
  View refund attributesClick or tap to expand
  Name
  amount
  Type
  integer
  Description
  Refund balance in minor units (pesewas for GHS).
- Name
  includes_transactions_before
  Type
  timestamp
  Description
  Snapshot cutoff time. Balance reflects all transactions created before this timestamp—transactions after this aren't included.
usdobjectBalance breakdown for US Dollars. Same structure as GHS—tracks available, pending, reserved, and refund amounts with snapshot timing.Click or tap to expand
- Name
  available
  Type
  object
  Description
  Settled funds ready for payout in USD.
  View available attributesClick or tap to expand
  Name
  amount
  Type
  integer
  Description
  Available amount in minor units (cents for USD).
- Name
  pending
  Type
  object
  Description
  Unsettled USD funds aging through the settlement window.
  View pending attributesClick or tap to expand
  Name
  amount
  Type
  integer
  Description
  Pending amount in minor units (cents for USD).
- Name
  reserved
  Type
  object
  Description
  Platform-managed reserves for USD disputes and chargebacks.
  View reserved attributesClick or tap to expand
  Name
  amount
  Type
  integer
  Description
  Reserved amount in minor units (cents for USD).
- Name
  refund
  Type
  object
  Description
  Funds you've set aside for processing customer refunds in USD.
  View refund attributesClick or tap to expand
  Name
  amount
  Type
  integer
  Description
  Refund balance in minor units (cents for USD).
- Name
  includes_transactions_before
  Type
  timestamp
  Description
  Snapshot cutoff for USD balance.

POST/balances

Retrieve your balance

Fetch the current balance state across all currencies for your application. This returns the most recent balance snapshot, typically updated hourly by background workflows. The snapshot aggregates all balance transactions up to a specific cutoff time—you'll see exactly when in the includes_transactions_before field. Use this for building dashboards, checking how much you can pay out, or reconciling your books against platform records.

The balance is scoped to your authenticated application, so you automatically see only your funds—no additional filtering needed. Each currency breaks down into four states: available funds ready for payout, pending funds aging through settlement, reserved funds held for refunds, and the cumulative refund amount. If you haven't received any payments yet or if snapshots haven't run, you'll see zero balances.

Request attributes

This endpoint requires no request body parameters—your application identity comes from the authentication token. Just POST to the endpoint and you'll get back your current balance state.

No parameters required.

Request

POST

/balances

curl https://api.zebo.dev/balances \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "balances": {
    "ghs": {
      "available": {
        "amount": 145000
      },
      "pending": {
        "amount": 32000
      },
      "reserved": {
        "amount": 0
      },
      "refund": {
        "amount": 0
      },
      "includes_transactions_before": "2024-12-24T14:00:00.000Z"
    },
    "usd": {
      "available": {
        "amount": 0
      },
      "pending": {
        "amount": 0
      },
      "reserved": {
        "amount": 0
      },
      "refund": {
        "amount": 0
      },
      "includes_transactions_before": "2024-12-24T14:00:00.000Z"
    }
  }
}

Understanding balances - Deep dive into balance states and snapshot timing
Balance Transactions - Individual transaction records
Payouts - How available balance is paid out
Understand payout settings - Configure automatic payouts