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.
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 exactly one of these two paths - there is no third option, and which path it takes is decided by the rule above, not by how urgent or small the change feels.

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.

​
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.