Skip to main content
The version is in the URL: every endpoint lives under /v1/. Inside v1, one rule protects every integration:
Additive-only. From general availability on 27. 09. 2026, every change inside v1 is additive: new endpoints, new optional request fields, new response fields, new enum values in open sets, new webhook events. Removing or renaming a field, retyping it, repurposing what it means, or changing the status code or error code of an existing response is a breaking change. Breaking changes are announced in the Changelog before they ship. Two narrow kinds of change ship with a dated changelog entry instead: bug fixes and stricter validation.
Because additions are the only planned change class, correct consumers are naturally forward-compatible. Three habits make that true on your side:
  • Ignore unknown fields when parsing responses and webhook payloads (every mainstream JSON library does this by default).
  • Treat documented-open sets as open: Transaction.source and other extensible vocabularies say so in their descriptions. Closed sets (marked with a JSON Schema enum) only grow with a documented changelog entry.
  • Branch on error.code, never on error.message. Error messages are text for people. We may reword them, for example to remove internal detail, and we note larger rewording in the changelog.

Additive vs. breaking, at a glance

Every change proposed inside v1 takes one of these two paths. The rule above decides the path, not how urgent or small the change feels. Bug fixes and stricter validation are the only exceptions, and they have their own rule below.

Additive changes ship the moment they're ready. Breaking changes are announced first and coexist with the old behavior for at least 12 months before anything is removed.

  • A new endpoint
  • A new optional request field
  • A new response field
  • A new value added to a documented open set (like Transaction.source)
  • A new webhook event type
None of these require anything from you. A parser that ignores unknown fields and a consumer that treats open sets as open keep working exactly as before.
  • Removing an endpoint, a field, or a webhook event
  • Renaming a field
  • Retyping a field
  • Repurposing what an existing field means
  • Changing the status code or error code of an existing response
  • Adding a value to a closed set (marked with a JSON Schema enum) outside a documented changelog entry
None of these ship silently inside v1. A removal, rename, retype or repurposing goes through the deprecation process below, and the eventual removal only lands in a new major version. A changed status code or error code is announced in the changelog before it ships.

Bug fixes and stricter validation

These two kinds of change ship with a dated Changelog entry, without the 12-month window:
  • A bug fix. A field or a response did not do what this reference says, and now it does. Example: on 04. 11. 2026 team_member_id started to name the staff member who booked a manual transaction, as the reference says, instead of the account owner.
  • Stricter validation. A value outside the documented limits, or one the server used to repair without telling you, now answers 422 with the field name in field_errors[]. Examples: the limits of 01. 11. 2026 and 02. 11. 2026.
The changelog entry names the fields, the old and the new behaviour, and the date. Removing, renaming or retyping a field is never a bug fix: it always follows the deprecation process below.

Webhooks are pinned per endpoint

Each webhook endpoint is pinned to the API version that is current when you create it (currently 2026-07), so the payload shape delivered to that endpoint never changes underneath your consumer. You cannot choose the version yourself. When a newer version exists, you upgrade without downtime:
  1. Create a second endpoint. It is pinned to the newest version.
  2. Prove your receiver with POST /v1/webhook_endpoints/{id}/test.
  3. Cut your consumer over, delete the old endpoint.

Deprecation

If we ever need to retire something inside v1 (rare by design):
  1. It is marked deprecated in the reference and the changelog, with the replacement named.
  2. It keeps working, unchanged, for at least 12 months from the deprecation notice.
  3. Removal only ships in a new major version (/v2/), never inside v1.
A v2, if it ever exists, runs side by side with v1; nothing forces a migration on a schedule you didn’t choose.

When something changes

Additions are announced in the changelog with the date, the surface touched, and a migration note when one is useful. Your integration requires no action for additive changes; the changelog exists so you can adopt new capabilities, not so you can survive them.