> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/payments/llms.txt
> Use this file to discover all available pages before exploring further.

# Balance changes

Balance changes report the ledger movement behind any flow, whichever payment business caused it. Read [Events overview](https://cobo.com/payments/payments/en/guides/events/overview.md) first for the envelope, deduplication, and the rules that apply to every event.

## Events on this page

| Event | What it notifies you of | Type |
| - | - | - |
| [`payment.account.balance.updated`](#payment-account-balance-updated) | One account's available balance moved for one token, and what caused it. This is the only event that reports what each account actually received. | **Standard** |

## `payment.account.balance.updated`

Fires when the available balance of a Payments account changes for a specific token.

It is also how you see **what each account actually received**. An order's `credited_amount`, for example, includes the portion split out as your developer fee, so it is not the merchant's credited amount. One order settlement produces one balance event per account involved.

### Event content

| Field | Type | Description |
| - | - | - |
| `data_type` | `string` | Always `PaymentAccountBalanceUpdate`. |
| `source_account` | `string` | Which account moved. For a merchant account this is the merchant ID; for the developer account it is `developer`. |
| `source_id` | `string` | The ID of the business record that caused the change: the order ID, refund ID, payout ID, bulk send item ID, or, for top-ups and unexpected deposits, the transaction ID. |
| `source_type` | `string` | What caused the change: • `OrderIn` — an order payment (including late payments after the order reached a final status). • `TopUp` — a top-up. • `UnexceptedIn` — an unexpected deposit. • `RefundOut` — a refund. • `Payout` — a payout. • `UnexceptedOut` — an unexpected outgoing payment. • `Allocation` — an allocation. • `BulkSend` — a bulk send. • `SettlementNetwork` — the settlement network. • `OnrampIn` — a fiat on-ramp deposit. |
| `token_id` | `string` | The token whose balance changed. |
| `amount` | `string` | The change, truncated to two decimal places. |
| `amount_raw` | `string` | The same change, in the token's own precision, without padded zeros (for example `100`, `0.123456`). |
| `balance_before` | `string` | The balance before the change, truncated to two decimal places. |
| `balance_before_raw` | `string` | The balance before the change, in the token's own precision. |
| `balance_after` | `string` | The balance after the change, truncated to two decimal places. |
| `balance_after_raw` | `string` | The balance after the change, in the token's own precision. |
| `flow_direction` | `string` | The direction of the change: • `in` — funds flow into the account. • `out` — funds flow out of the account. |
| `update_time` | `integer` | When the balance was updated, in Unix timestamp (seconds). |

### Sample events

Each sample shows the `data` object only. The envelope around it is the same for every event — see [Event structure](https://cobo.com/payments/payments/en/guides/events/overview.md#event-structure).

#### An order credits the merchant and the developer

One order settlement produces one event per account. The two together add up to the order's `credited_amount`.

```json theme={null}
{
  "data_type": "PaymentAccountBalanceUpdate",
  "source_account": "M1001",
  "source_id": "order_001",
  "source_type": "OrderIn",
  "token_id": "ETH_USDC",
  "amount": "100.00",
  "amount_raw": "100",
  "balance_before": "1250.00",
  "balance_before_raw": "1250",
  "balance_after": "1350.00",
  "balance_after_raw": "1350",
  "flow_direction": "in",
  "update_time": 1744690100
}
```

```json theme={null}
{
  "data_type": "PaymentAccountBalanceUpdate",
  "source_account": "developer",
  "source_id": "order_001",
  "source_type": "OrderIn",
  "token_id": "ETH_USDC",
  "amount": "2.00",
  "amount_raw": "2",
  "balance_before": "830.00",
  "balance_before_raw": "830",
  "balance_after": "832.00",
  "balance_after_raw": "832",
  "flow_direction": "in",
  "update_time": 1744690100
}
```

#### A payout leaves the developer account

`flow_direction` is `out` and `source_id` is the payout ID.

```json theme={null}
{
  "data_type": "PaymentAccountBalanceUpdate",
  "source_account": "developer",
  "source_id": "payout_001",
  "source_type": "Payout",
  "token_id": "ETH_USDC",
  "amount": "500.00",
  "amount_raw": "500",
  "balance_before": "832.00",
  "balance_before_raw": "832",
  "balance_after": "332.00",
  "balance_after_raw": "332",
  "flow_direction": "out",
  "update_time": 1744700600
}
```

## Keeping your own balances current

Webhook messages do not carry real-time balances, so that the values you read cannot be stale relative to concurrent activity.

* **To update balances as events arrive:** call [List merchant balances](https://cobo.com/payments/payments/en/api-references/payment/list-merchant-balances.md) or [Get developer balances](https://cobo.com/payments/payments/en/api-references/payment/get-developer-balance.md) when a webhook lands.
* **To reconcile fees:** use the transaction query endpoints or [Generate reports](https://cobo.com/payments/payments/en/api-references/payment/generate-reports.md).
* **To avoid running out of gas:** poll [List Fee Station token balance](https://www.cobo.com/developers/v2/api-references/feestation/list-fee-station-token-balances) and alert on your own consumption rate. Several failure codes across payouts, refunds, and bulk sends trace back to an empty Fee Station.