Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
New

API versioning

How API versioning works, and what happens when a resource is unavailable or deprecated on the requested version

Commerce Layer's versioning system uses date-stamped URL path segments. Clients select a version by including it in the request URL, appended to the base endpoint:

.../api/{{version}}/...

Where {{version}} can be one of:

  • 2017-08 — default version

  • 2026-05 — latest version

For example:

GET /api/2017-08/orders # default version
GET /api/2026-05/orders # latest version
GET /api/orders # defaults to the 2017-08 version

We recommend always specifying the version explicitly in the request URL. The 2017-08 default is fixed and cannot be configured, so every other version, starting from 2026-05, must be requested explicitly. Doing so keeps your integration predictable and lets us support more than two versions concurrently as the API evolves.

API resources are version-aware — each one is tied to a specific set of supported versions. At request time, the requested version date is compared against those declarations to produce one of three outcomes:

Status
Description
Supported

The resource is fully available at the requested version. This applies to most shared resources (e.g. orders, customers, addresses, etc.).

Unavailable

The resource is newer than the requested version. The API returns an HTTP 400 Bad request error with code UNSUPPORTED (see example).

Deprecated

The resource was introduced in an earlier version and is being phased out. It continues to work, but the document-level meta includes an entry containing deprecation details that identify the resource by type and name, with optional information (see example).

The same comparison applies to single fields and relationships, not only to whole resources. A resource available on both versions can still expose some attributes or relationships on one version only (e.g. an order's payment_sessions relationship exists on 2026-05 only, while its payment_method relationship dates back to 2017-08 and is deprecated on 2026-05):

  • A field or relationship that is newer than the requested version is not part of the resource at that version — it's omitted from the response, and sending it in a request body returns an HTTP 400 Bad request error with code PARAM_NOT_ALLOWED.

  • A field or relationship that is older than the requested version keeps working, and the document-level meta includes a deprecation entry of type field or relationship.

On orders, using the legacy payment flow (e.g. fetching the available payment methods or customer payment sources) adds a deprecation entry of type resource named old_payment_workflow, regardless of the requested version.

Examples

Fetching a fully available resource

The following request fetches an SKU, a resource that is fully available on all versions:

On success, the API responds with a 200 OK status code, returning a single resource object with standard meta information:

Since no version path segment was specified in the request, the meta.api_version defaults to 2017-08. Also, since the resource is fully available on all versions, no meta.deprecations info is present.

Fetching a resource available on the latest version only

The following request correctly fetches a payment session, a resource that is available only on the 2026-05 version:

On success, the API responds with a 200 OK status code, returning a single resource object with standard meta information:

Since the resource is available on the requested version, no meta.deprecations info is present. Specifying 2026-05 here is required, since 2017-08 is the fixed default version and omitting the version path segment would not resolve to 2026-05.

Fetching an unavailable resource

The following request tries to fetch a payment session, a resource that is available only on the 2026-05 version, without specifying the correct version:

The API responds with a 400 Bad request status code, returning additional information within the errors array:

Since no version path segment was specified in the request, the API version defaults to 2017-08, where the resource is not available.

Fetching a deprecated resource

The following request tries to fetch a payment method, a resource that is available only on the 2017-08 version but deprecated on the 2026-05 version:

On success, the API responds with a 200 OK status code, returning a single resource object with meta information that also contains deprecation details:

Fetching a resource with deprecated fields and relationships

The following request fetches an order, a resource available on all versions. Some of its fields and relationships, however, are deprecated on the 2026-05 version:

On success, the API responds with a 200 OK status code, returning a single resource object. The deprecated items are listed in the document-level meta, each one identified by its type (field or relationship) and name:

Deprecated fields and relationships keep working on the requested version, but we recommend migrating away from them. The same fields and relationships are not deprecated on 2017-08, so no meta.deprecations info is present there.

Last updated