Version number
A version number has three parts,x.y.z:
X: the Core version. Y: the Major version. Z: the Minor version.
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 mandatoryX-Api-Version header on every call. A call without this header is rejected.
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.Stable → Stable - pending deprecation
You get at least 6 months to migrate to a newer version, with availability and performance maintained.
1.*.*, or a major such as 1.2.*) and when it takes effect.
Webhooks
Webhooks are not versioned; there is a single version. TheX-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 page, where you can view the rendered reference or download the OpenAPI spec for each.What’s next
Releases
Every published version, with docs and OpenAPI downloads.
Rate limits
Per-token request limits and backoff strategy.
Errors
HTTP codes and Paylead error envelopes.