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 version2026-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 versionAPI 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:
The resource is fully available at the requested version. This applies to most shared resources (e.g. orders, customers, addresses, etc.).
The resource is newer than the requested version. The API returns an HTTP 400 Bad request error with code UNSUPPORTED (see example).
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 requesterror with codePARAM_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
fieldorrelationship.
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:
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:
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:
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:
Last updated