> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paylead.fr/llms.txt
> Use this file to discover all available pages before exploring further.
# Versioning
Paylead versions its API so that our services can keep evolving while your integration stays stable. New features ship in new versions, and you upgrade on your own schedule. Paylead recommends running the latest version to get new functionality and the best experience.
**Why this matters.** The version policy tells you what can change without warning (backward-compatible minors) and what requires you to update your integration (major and core releases).
## Version number
A version number has three parts, `x.y.z`:
**X**: the **Core** version. **Y**: the **Major** version. **Z**: the **Minor** version.
This is **not** standard Semantic Versioning. Minor releases (`z`) are always backward compatible; major (`y`) and core (`x`) releases are backward incompatible and may require you to update your code.
## Select a version
The version is **not** part of the URL path. You select it with the mandatory **`X-Api-Version`** header on every call. **A call without this header is rejected.**
```http theme={null}
X-Api-Version: 2.0.3
```
The current production-grade version is the **Core 2** line; use it for any new integration. See [Environments](/program/user-journey/environments) for the base URLs and [Authentication](/program/user-journey/authentication) for the bearer token.
## What ships in each release
### Minor releases (`z`): backward compatible
Safe to adopt without changing your code. A non-exhaustive list of changes that ship in a minor:
| API element | Change event |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Path | Adding an endpoint |
| Request body | Adding an authentication method |
| Request body | Adding an optional field |
| Response body | Changing the functional behavior of a field (e.g. `is_consumed` meaning "has consumed" → "the Offer is fully consumed") |
| Response body | Adding an attribute |
| Response body | Removing an element from an enum |
| Status code | Changing the status code of an existing query (e.g. `400` → `422`, `400` → `409`) |
### Major releases (`y`): backward incompatible
Moving to a new major may require you to update your integration:
| API element | Change event |
| ----------------------- | ------------------------------------------------------------------- |
| Path | Removing an endpoint |
| Request body | Adding a required field (header, body property, or query parameter) |
| Request body | Hardening validation of a property (`anyOf` / `oneOf` / `allOf`) |
| Authentication | Deleting or updating an authentication method |
| Request / Response body | Changing an attribute data type (e.g. `integer` → `float`) |
| Response body | Renaming an attribute (e.g. `name` → `productName`) |
| Response body | Removing an attribute |
| Response body | Adding an element to an enum |
| Status code | Changing a status code in the `2xx` range |
### Core releases (`x`): backward incompatible
The deepest changes. Moving to a new core will require you to update your integration:
| API element | Change event |
| ------------- | --------------------------------------------------------- |
| Request body | Changing the request format (e.g. XML → JSON) |
| Response body | Changing the response format (e.g. XML → JSON) |
| Global | A cross-cutting change (response envelope, pagination, …) |
## API lifecycle
Each major version (`X.Y.*`) moves through the following statuses. Every minor follows the lifecycle of its major.
| Status | Meaning | Duration |
| -------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------- |
| **Experimental** | The definition may change at any time. You must explicitly request it via the `X-Api-Version` header. | Not applicable |
| **Stable** | The definition is stable. | ≥ 6 months |
| **Stable - pending deprecation** | Still stable, but the removal date is now fixed. | = 6 months |
| **Deprecated** | Still available, but you should migrate. Requests no longer count toward performance metrics. | ≥ 12 months |
| **Gone** | No longer available. Requests return `410 Gone`. | Not applicable |
## Deprecation timeline
Paylead communicates every deprecation to your Program **by email**.
You get **at least 6 months** to migrate to a newer version, with availability and performance maintained.
A further **12 months** of availability follows, but performance is no longer guaranteed.
On the removal date, requests targeting the version return `410 Gone`.
Each deprecation notice states **what** is being deprecated (an entire core line such as `1.*.*`, or a major such as `1.2.*`) and **when** it takes effect.
## Webhooks
Webhooks are **not** versioned; there is a single version. The `X-Api-Version` header does not apply to Webhook payloads.
## Older versions
Versions before the current core (including the pre-platform per-component specs) are archived on the [Releases](/program/api/releases) page, where you can view the rendered reference or download the OpenAPI spec for each.
## What's next
Every published version, with docs and OpenAPI downloads.
Per-token request limits and backoff strategy.
HTTP codes and Paylead error envelopes.