API versioning and upgrades

Ledgerline versions its API by date. A version changes only when a release contains a breaking change, and your integration stays on the version it was built against until you choose to move. This page explains what is versioned, how to pin or test a version and how to upgrade safely.

How versions work

Each version is named for the day it was released. The current version is 2026-09-01. Versions still supported:

When you create an organization, it is pinned to the version that is current at that moment. Every request without a version header runs against that pinned version, no matter how many versions are released afterwards.

What counts as breaking

A change gets a new version if it could break a correct integration:

• Renaming or removing a field, header, event type or endpoint.
• Changing the type, format or meaning of a field.
• Making an optional parameter required.
• Changing which status code or error code a failure returns.

These ship without a new version, because a correct client must tolerate them:

• Adding a new endpoint, optional parameter, field, event type or error code.
• Adding a new value to a field that is documented as open, such as a new rail.
• Changing the order of fields or list items where order is not documented.
• Changing the content of human-readable message strings.

Choosing a version per request

Override the pinned version for a single request with the Ledgerline-Version header:

curl https://api.ledgerline.dev/v1/accounts/acc_01J9QK5N7C/balances \
  -H "Authorization: Bearer $LEDGERLINE_API_KEY" \
  -H "Ledgerline-Version: 2026-09-01"

The SDKs expose it as apiVersion (Node) and api_version (Python). Pinning in code makes behavior explicit and survives a change to the account default. The same version is echoed in the Ledgerline-Version response header and in api_version on every webhook event.

Webhook versions

Each webhook endpoint has its own API version, which defaults to the organization's pinned version when you create it. Events sent to that endpoint use that version's object shapes. You can change the version of an endpoint without touching your API calls, which lets you upgrade receivers and callers separately. See Webhooks overview.

Upgrading safely

1. Read the changelog for every version between yours and the target. Each lists breaking changes under a heading. See the API changelog.
2. Test in the sandbox. Send Ledgerline-Version with the new version on sandbox requests from your test suite.
3. Upgrade webhooks first. Create a second endpoint at the new version, run both for a few days and compare.
4. Roll out per service. Set the version header on one service at a time.
5. Change the account default. In the dashboard, open Developers > API version and choose Upgrade. After that, requests without a header use the new version.
6. Roll back if needed. You can return to the previous version for 72 hours after an upgrade.

Example: what changed in 2026-09-01

The most visible change in 2026-09-01 is that available on account balances now subtracts pending outflows. Under 2026-06-15 the same field equals the posted balance. If you compare the two across versions, a payout in flight shows up in available only on the new version. See Account balances.

Deprecation policy

A version is supported for at least 18 months after the next one ships. Ledgerline announces a retirement date at least 6 months ahead through the dashboard, the changelog and email to the account owners. After the retirement date, requests pinned to the retired version are served with the oldest supported version.

SDK versions

SDK releases are independent of API versions and follow semantic versioning. An SDK pins a default API version at release time but obeys apiVersion if you set it. See Node.js SDK and Python SDK.