SDK ⇆ API compatibility matrix

Every Paylera SDK is wire-compatible with the dated API version it was generated against, plus the immediately-preceding and immediately-following versions. This document records the current matrix and the policy for maintaining it.

Current compatibility (live, pre-v1)

The SDK suite is pre-release (0.x). All eleven packages target a single API date today; the matrix has one cell.

SDK package	SDK version	Paylera-Api-Version (default)	Compatible with API dates
`@paylera/sdk`	`0.x`	`2026-05-01`	`2026-05-01`
`@paylera/react`	`0.x`	(relies on `@paylera/sdk`)	`2026-05-01`
`@paylera/server`	`0.x`	(relies on `@paylera/sdk`)	`2026-05-01`
`@paylera/cli`	`0.x`	(relies on `@paylera/sdk`)	`2026-05-01`
`Paylera.Sdk`	`0.x`	`2026-05-01`	`2026-05-01`
`Paylera.AspNetCore`	`0.x`	(relies on `Paylera.Sdk`)	`2026-05-01`
`paylera` (Python)	`0.x`	`2026-05-01`	`2026-05-01`
`paylera-fastapi`	`0.x`	(relies on `paylera`)	`2026-05-01`
`github.com/paylera/paylera-go`	`0.x`	`2026-05-01`	`2026-05-01`
`dev.paylera:paylera-sdk`	`0.x`	`2026-05-01`	`2026-05-01`
`dev.paylera:paylera-spring-boot-starter`	`0.x`	(relies on the SDK)	`2026-05-01`

The default Paylera-Api-Version is set at typed-client construction; merchants can override per-client to pin a different date.

Policy: how SDK ⇆ API compatibility is decided

A given SDK release is wire-compatible with three API dates:

N — the API version it was generated against (info.version in the OpenAPI spec at generation time)
N − 1 — the immediately-preceding dated release
N + 1 — the immediately-following dated release

The N−1 / N+1 windows give merchants a deployment lane wide enough to upgrade their SDK without coordinating a same-day API-version bump. Any spec change that breaks N−1 or N+1 compat requires either:

A new SDK major (breaking change announced + 90-day deprecation window), or
A spec amendment that re-establishes the compat window (additive-only changes within a dated release are always allowed).

What counts as a “breaking change”

Spec change	N−1 / N+1 compat?
New endpoint added	✓ compatible
New optional field on existing response	✓ compatible
New optional request parameter	✓ compatible
Field renamed	✗ breaks
Field removed	✗ breaks
Required→optional on response	✓ compatible
Optional→required on request	✗ breaks
Enum value added	✓ compatible
Enum value removed	✗ breaks
HTTP status code added	✓ compatible (clients must handle unknown 4xx/5xx gracefully)
HTTP status code reused for different semantics	✗ breaks
Auth-scheme change	✗ breaks

CI enforcement

The cross-language conformance harness at sdks/_conformance/ exercises each SDK’s relay against the current API spec — that’s the N cell.

The matrix becomes meaningful once a second dated API release ships. At that point, CI gains a per-SDK matrix dimension:

strategy:
  matrix:
    api_version: ["2026-05-01", "2026-08-01"]  # add as new dates land
    sdk_version: ["1.0.x", "1.1.x"]

The workflow at .github/workflows/sdk-compat-matrix.yml is wired today with the single-cell matrix and grows in place.

Future cells (illustrative)

Once a second API date lands, the matrix will read like:

SDK version	API 2026-05-01	API 2026-08-01
`1.0.x` (generated against 2026-05-01)	✓ N	✓ N + 1
`1.1.x` (generated against 2026-08-01)	✓ N − 1	✓ N
`1.2.x` (generated against 2026-08-01 with bugfix)	✓ N − 1	✓ N

Anything outside the N ± 1 window prints a runtime warning when the client detects the mismatch via the Paylera-Api-Version response header.

Source of truth for this matrix

This page is the source-of-truth for the wire-compatibility statement. The sdks/RELEASE-CHECKLIST.md compat-matrix-update step runs whenever a coordinated SDK release is cut.