> ## 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, so your integration never breaks under you.

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.

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.

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

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