Skip to content
Paylera

Versioning

Paylera versions the API by date. You pin the version your code expects; we keep that version stable; we ship breaking changes behind a new dated version.

The version header

Paylera-Version: 2026-04-01

Every response echoes the version the request was processed against:

Paylera-Version: 2026-04-01

If you don’t send a header, the API uses the version that was the default at the time your token was created. New tokens always use the current default. This means your integration won’t silently change versions just because the platform default rolled forward.

What’s a breaking change

Breaking changes ship behind a new version. Examples:

  • Removing a field, endpoint, or enum value.
  • Renaming a field.
  • Changing the type of a field (string → int, etc.).
  • Changing the meaning of a field.
  • Changing a default behaviour where the previous behaviour is no longer reachable.
  • Changing an HTTP status code returned for a known scenario.

What isn’t

These are non-breaking and ship at any version:

  • Adding a new optional request field.
  • Adding a new field to a response.
  • Adding a new enum value (clients should treat unknown enum values as unknown, not as errors).
  • Adding a new endpoint.
  • Adding a new event type.
  • Adding a new error code.
  • Changing internal behaviour that doesn’t change observable outputs.

Version overlap

When a new dated version ships:

  • Both versions remain serviceable for at least 12 months after the new one ships.
  • Responses on the old version include an RFC 8594 Sunset header pointing at the deprecation date and a Deprecation header flagging the version.
  • Migration notes are published in the Changelog the same day.

Reading the changelog

Every dated version has an entry. Look for:

  • Breaking — what changed in shape; how to migrate.
  • New — endpoints / fields added.
  • Behavioural — non-shape changes (timeouts, default rounding, retry policy) that may affect you.

Pinning in production

Pin the version your code was written against. When you intentionally upgrade:

  1. Read the changelog from your current version to the new one.
  2. Update your client code for any breaking changes.
  3. Roll out with the new Paylera-Version header.
  4. Watch your error rate for 24 hours; revert by changing the header if needed.

There is no globally-versioned URL prefix (/v2/); only the header. The /v1/ in the URL refers to the API generation, not the dated version.

Beta features

Some features ship behind a beta header:

Paylera-Beta: hosted-checkout-2

Beta features may break shape without a new dated version. They’re flagged as beta in the docs and in the dashboard. Don’t depend on them for production until they graduate.

Webhook event versioning

Events also carry schema_version. Within a major version, fields are added freely; never removed or renamed. A new major version (schema_version: 2) ships behind a separate event type (subscription.activated.v2) with the same overlap and sunset policy as the API.

SDK versioning

SDKs ship per dated version. The @paylera/sdk@2026.4.x line targets 2026-04-01. Upgrading the SDK without changing the pinned API version pulls in non-breaking improvements; upgrading the line picks up a new API version.