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

# API versions

> How the Payments-Version header works, what counts as a breaking change, and how versions roll.

The Payments API is versioned by date. A version is a contract: the shape of every request and response under that version does not change in a breaking way.

| | |
| - | - |
| Current version | `2026-11-01` |
| Header | `Payments-Version` |
| Versions accepted today | `2026-11-01` |

## Send the version

Send the version you built against on every request:

```bash theme={null}
curl https://api.tagada.io/v1/payments/pay_0123456789ab \
  -H "Authorization: Bearer tsk_test_..." \
  -H "Payments-Version: 2026-11-01"
```

* **No header:** the request runs on the current version.
* **A version the API does not support:** `400` with code `parameter_invalid` and `param: "Payments-Version"`.
* **Every response** carries `Payments-Version` with the version that served it.

> [!TIP]
>
> Always send the header. Without it, your integration follows the current version, so a future version could change a response your code reads.

The official clients send the header for you: `@tagadapay/core-js/payments-v3` sends the version it was generated from. See [SDK versions](https://docs.tagada.io/developer-tools/sdk-versions.md).

## What is not a breaking change

These changes ship inside the current version, without notice. Build your integration to tolerate them:

* New endpoints and new resources.
* New optional request parameters.
* New fields in responses.
* New values in response enums. Enums marked `x-extensible-enum` in the [OpenAPI document](https://docs.tagada.io/payments-api/reference/introduction.md) are open: treat an unknown status, reason or error code as a value you did not plan for, not as a failure of your parser.
* New error codes. Existing error codes are never renamed.
* A different order of fields in a response.

## What is a breaking change

A breaking change gets a new dated version. Examples: removing or renaming a field, changing a field's type, adding a required request parameter, changing the meaning of a status. A new version is only created when a response shape changes.

Every change to the API's OpenAPI document is checked for breaking changes before it merges.

## How versions roll

When a second version exists, the API will keep serving the older one to callers that pin it in the header. The upgrade guide for that version will list every change and the code to update. There is only one version today, so there is nothing to upgrade.

## Version history

| Version | Status | Changes |
| - | - | - |
| `2026-11-01` | Current (Preview) | First version of the Payments API. |

## V2 is not dated

The Commerce API (V2, `https://api.tagada.io/api/public/v1`) does not use `Payments-Version`. Its contract evolves additively. `@tagadapay/node-sdk` sends an `X-Tagada-Api-Version` header (option `apiVersion`), but the Commerce API does not read it today. See [V2 or V3](https://docs.tagada.io/payments-api/v2-or-v3.md).


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