---
title: "Read the aging balance"
description: "Analyse net outstanding amounts by age bucket, currency, and customer account."
canonical: https://developer.billabex.com/en/guides/aging-balance/
lang: en
alternate: https://developer.billabex.com/fr/guides/balance-agee/
last-updated: 2026-09-12
---

# Read the aging balance

> Analyse net outstanding amounts by age bucket, currency, and customer account.

Source: https://developer.billabex.com/en/guides/aging-balance/
Language: English (en)
French version: https://developer.billabex.com/fr/guides/balance-agee/

The aging balance spreads the amounts still to be received across five buckets. It is net of
unallocated credit notes, which are applied first to the oldest amounts of the same account in the
same currency.

Accounts written off are excluded. The balance converts no currency: every amount stays in the one
it was issued in.

## Authorization

Both endpoints accept the OAuth scope `accounts:read` or `accounts:all`.

## Read the totals

```http
GET https://next.billabex.com/api/public/v1/aging-balance?organizationId=ORGANIZATION_ID
Authorization: Bearer YOUR_ACCESS_TOKEN
```

The response carries one entry per currency. Each bucket reports its net amount along with the
number of accounts and invoices that still hold a positive amount in it.

```json
{
  "byCurrency": [
    {
      "currencyCode": "EUR",
      "notDue": 12500,
      "notDueAccountCount": 4,
      "notDueInvoiceCount": 7,
      "d0_30": 8200,
      "d0_30AccountCount": 3,
      "d0_30InvoiceCount": 5,
      "d31_60": 4100,
      "d31_60AccountCount": 2,
      "d31_60InvoiceCount": 2,
      "d61_90": 1800,
      "d61_90AccountCount": 1,
      "d61_90InvoiceCount": 1,
      "d90Plus": 900,
      "d90PlusAccountCount": 1,
      "d90PlusInvoiceCount": 1
    }
  ]
}
```

## Break it down by account

`currencyCode` is required. The list uses `first` and `after`, like every other paginated endpoint.

```http
GET https://next.billabex.com/api/public/v1/aging-balance/accounts?organizationId=ORGANIZATION_ID&currencyCode=EUR&first=20&sortBy=d90Plus&sortOrder=desc
Authorization: Bearer YOUR_ACCESS_TOKEN
```

Each row carries the five buckets, plus `totalOutstanding`, `overdueOutstanding` and
`overdueRate`. A rate of `100` means the whole outstanding amount of that account is past due.

Sortable fields: `fullName`, `notDue`, `d0_30`, `d31_60`, `d61_90`, `d90Plus`, `totalOutstanding`,
`overdueOutstanding` and `overdueRate`.

Available filters:

| Field                     | Operators                                                             |
| ------------------------- | --------------------------------------------------------------------- |
| `accountName`             | `contains`, `startsWith`, `equals`                                    |
| `tags`                    | `containsAny`, `containsAll`, `containsNone`, `isEmpty`, `isNotEmpty` |
| `dunningPaused`           | `isTrue`, `isFalse`                                                   |
| `paymentMethod`, `source` | `is`, `isNot`, `isAnyOf`, `isEmpty`, `isNotEmpty`                     |
| `collectiveProceeding`    | `is`, `isNot`, `isAnyOf`                                              |
| Amounts and rates         | `equals`, `greaterThan`, `lessThan`, `between`                        |

For example, customers with more than 60 % of their outstanding amount past due:

```http
GET https://next.billabex.com/api/public/v1/aging-balance/accounts?organizationId=ORGANIZATION_ID&currencyCode=EUR&filters=overdueRate%3AgreaterThan%3A60
Authorization: Bearer YOUR_ACCESS_TOKEN
```

The `pageInfo.endCursor` cursor is bound to the currency, the filters, the sort and the page size.
Drop it as soon as any of those changes.

## MCP

The `get-aging-balance` and `list-aging-balance-by-account` tools return the same data with the
`mcp:read` scope. The list accepts `first`, `after`, `filters`, `sortBy` and `sortOrder`.

---

Billabex developer portal. OpenAPI specification: https://developer.billabex.com/openapi.json.
Agent instructions: https://developer.billabex.com/llms.txt. Complete documentation: https://developer.billabex.com/llms-full.txt.