---
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-10-25
---

# 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
    }
  ]
}
```

## Compare with a past instant

Add `receivablesAt`, an ISO 8601 instant, to also get what invoices still owed strictly before it,
by currency. The rule is the buckets' own: only invoices with a positive balance count, and
accounts written off today are left out on both sides. Today's invoices (the sum of the five
buckets) therefore compare directly with that amount.

```http
GET https://next.billabex.com/api/public/v1/aging-balance?organizationId=ORGANIZATION_ID&receivablesAt=2026-10-01T00:00:00.000Z
Authorization: Bearer YOUR_ACCESS_TOKEN
```

```json
{
  "byCurrency": [],
  "receivablesAt": {
    "at": "2026-10-01T00:00:00.000Z",
    "byCurrency": [{ "currencyCode": "EUR", "amount": 24800 }]
  }
}
```

`receivablesAt` is `null` when the organization's financial history does not cover that instant.

## 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`;
`get-aging-balance` accepts `receivablesAt`.

---

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.