Skip to main content
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.
The current production-grade version is the Core 2 line; use it for any new integration. See Environments for the base URLs and 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:

​
Major releases (y): backward incompatible

Moving to a new major may require you to update your integration:

​
Core releases (x): backward incompatible

The deepest changes. Moving to a new core will require you to update your integration:

​
API lifecycle

Each major version (X.Y.*) moves through the following statuses. Every minor follows the lifecycle of its major.

​
Deprecation timeline

Paylead communicates every deprecation to your Program by email.
1

Stable → Stable - pending deprecation

You get at least 6 months to migrate to a newer version, with availability and performance maintained.
2

Deprecated

A further 12 months of availability follows, but performance is no longer guaranteed.
3

Gone

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