> ## Documentation Index
> Fetch the complete documentation index at: https://vexioncards.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> URL-versioned major, additive-only inside v1. Bug fixes and stricter validation ship with a dated changelog entry.

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](https://vexioncards.mintlify.site/api-reference/changelog.md) before they ship. Two narrow kinds of change ship with a dated changelog entry instead: [bug fixes and stricter validation](#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.

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E5F6FF','primaryBorderColor':'#36C6FA','primaryTextColor':'#0B3A4A','lineColor':'#2BA8D9','secondaryColor':'#F4FCFF','tertiaryColor':'#FFFFFF','fontFamily':'Manrope, ui-sans-serif, system-ui, sans-serif'}}}%%
flowchart TD
    A["Change proposed inside v1"] --> B{"Additive?"}
    B -->|"new endpoint / new optional request field /<br/>new response field / new enum value in an open set /<br/>new webhook event"| C["Ships directly"]
    C --> D["Noted in the changelog"]
    D --> E["No action required from you -\nunknown fields are already ignored"]
    B -->|"removes, renames, retypes,<br/>or repurposes something that exists"| F["Marked deprecated\nin the reference and the changelog"]
    F --> G["Keeps working, unchanged,\nfor at least 12 months"]
    G --> H["Removal ships only\nin a new major version (/v2/)"]
```

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.

> [accordion] Additive - safe, ships anytime, no announcement needed
>
> * 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.

> [accordion] Breaking - announced first, never silent
>
> * 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](https://vexioncards.mintlify.site/api-reference/changelog.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.