> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core/api-versioning.md).

# 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](/core/api-specification.md#base-endpoint):

```http
.../api/{{version}}/...
```

Where `{{version}}` can be one of:

* `2017-08` — default version
* `2026-05` — latest version

For example:

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

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}
Always use one of the versions listed above. Any other date-stamped segment (e.g. `2020-01` or `2030-01`) is not a valid version: the API returns an HTTP `400 Bad request` error with code `UNSUPPORTED`, exactly as it does for a resource that is [unavailable](#fetching-an-unavailable-resource) on the requested version.
{% endhint %}

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:

<table><thead><tr><th width="160">Status<select><option value="3bd738d49dfd40729a57cf0d8f7eee1d" label="Supported" color="green"></option><option value="61994c49660d434e90cbc0f2287991bb" label="Unavailable" color="red"></option><option value="692e8fe6d3d0424bbd38ee92c3839ba4" label="Deprecated" color="orange"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><span data-option="3bd738d49dfd40729a57cf0d8f7eee1d">Supported</span></td><td>The resource is <em>fully available</em> at the requested version. This applies to most shared resources (e.g. orders, customers, addresses, etc.).</td></tr><tr><td><span data-option="61994c49660d434e90cbc0f2287991bb">Unavailable</span></td><td>The resource is <em>newer</em> than the requested version. The API returns an HTTP <code>400 Bad request</code> error with code <code>UNSUPPORTED</code> (<a href="#fetching-an-unavailable-resource">see example</a>).</td></tr><tr><td><span data-option="692e8fe6d3d0424bbd38ee92c3839ba4">Deprecated</span></td><td>The resource was introduced in an <em>earlier</em> 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 (<a href="#fetching-a-deprecated-resource">see example</a>).</td></tr></tbody></table>

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](/core/api-specification.md#deprecation-warnings) of type `field` or `relationship`.

{% hint style="info" %}
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.
{% endhint %}

## Examples

### Fetching a fully available resource

{% tabs %}
{% tab title="Request" %}
The following request fetches an SKU, a resource that is fully available on all versions:

<pre class="language-shell"><code class="lang-shell">curl -g -X GET \
<strong>  'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde' \
</strong>  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'
</code></pre>

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning a single resource object with standard meta information:

<pre class="language-json"><code class="lang-json">{
  "data": {
    "id": "xYZkjABcde",
    "type": "skus",
    "links": { ... },
    "attributes": { ... },
    "relationships": { ... },
    "meta": {
<strong>      "created_with_version": "2017-08"
</strong>    }
  },
  "meta": {
<strong>    "api_version": "2017-08",
</strong><strong>    "api_versions": [ "2017-08", "2026-05" ],
</strong>    "mode": "test",
    "organization_id": "wBstRPzLrk",
    "trace_id": "d95e207e4358198129f062000650759c3a1b7f4e8d2c6a0b5e9f1d3c7a4b8e20"
  }
}
</code></pre>

{% hint style="info" %}
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.
{% endhint %}
{% endtab %}
{% endtabs %}

### Fetching a resource available on the latest version only

{% tabs %}
{% tab title="Request" %}
The following request correctly fetches a payment session, a resource that is available only on the `2026-05` version:

<pre class="language-shell"><code class="lang-shell">curl -g -X GET \
<strong>  'https://yourdomain.commercelayer.io/api/2026-05/payment_sessions/ABcdeXYzkj' \
</strong>  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'
</code></pre>

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning a single resource object with standard meta information:

<pre class="language-json"><code class="lang-json">{
  "data": {
    "id": "ABcdeXYzkj",
    "type": "payment_sessions",
    "links": { ... },
    "attributes": { ... },
    "relationships": { ... },
    "meta": {
<strong>      "created_with_version": "2026-05"
</strong>    }
  },
  "meta": {
<strong>    "api_version": "2026-05",
</strong><strong>    "api_versions": [ "2026-05" ],
</strong>    "mode": "test",
    "organization_id": "wBstRPzLrk",
    "trace_id": "d95e207e4358198129f062000650759c3a1b7f4e8d2c6a0b5e9f1d3c7a4b8e20"
  }
}
</code></pre>

{% hint style="info" %}
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`.
{% endhint %}
{% endtab %}
{% endtabs %}

### Fetching an unavailable resource

{% tabs %}
{% tab title="Request" %}
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:

<pre class="language-shell"><code class="lang-shell">curl -g -X GET \
<strong>  'https://yourdomain.commercelayer.io/api/payment_sessions/xYZkjABcde' \
</strong>  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'
</code></pre>

{% endtab %}

{% tab title="Response" %}
The API responds with a `400 Bad request` status code, returning additional information within the `errors` array:

<pre class="language-json"><code class="lang-json">{
  "errors": [
    {
<strong>      "title": "API is not supported by the current version",
</strong>      "detail": "The requested API is not supported by the current version you are using, please check our docs for further information.",
<strong>      "code": "UNSUPPORTED",
</strong><strong>      "status": "400"
</strong>    }
  ]
}
</code></pre>

{% hint style="info" %}
Since no version path segment was specified in the request, the API version defaults to `2017-08`, where the resource is not available.
{% endhint %}
{% endtab %}
{% endtabs %}

### Fetching a deprecated resource

{% tabs %}
{% tab title="Request" %}
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:

<pre class="language-shell"><code class="lang-shell">curl -g -X GET \
<strong>  'https://yourdomain.commercelayer.io/api/2026-05/payment_methods/CDabfWKjoe' \
</strong>  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'
</code></pre>

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning a single resource object with meta information that also contains [deprecation details](/core/api-specification.md#deprecation-warnings):

<pre class="language-json"><code class="lang-json">{
  "data": {
    "id": "CDabfWKjoe",
    "type": "payment_methods",
    "links": { ... },
    "attributes": { ... },
    "relationships": { ... },
    "meta": {
<strong>      "created_with_version": "2026-05"
</strong>    }
  },
  "meta": {
<strong>    "api_version": "2026-05",
</strong><strong>    "api_versions": [ "2017-08" ],
</strong>    "mode": "test",
    "organization_id": "wBstRPzLrk",
    "trace_id": "d95e207e4358198129f062000650759c3a1b7f4e8d2c6a0b5e9f1d3c7a4b8e20",
<strong>    "deprecations": [
</strong><strong>      {
</strong><strong>        "type": "resource",
</strong><strong>        "name": "payment_method"
</strong><strong>      }
</strong><strong>    ]
</strong>  }
}
</code></pre>

{% endtab %}
{% endtabs %}

### Fetching a resource with deprecated fields and relationships

{% tabs %}
{% tab title="Request" %}
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:

<pre class="language-shell"><code class="lang-shell">curl -g -X GET \
<strong>  'https://yourdomain.commercelayer.io/api/2026-05/orders/ABcdeXYzkj' \
</strong>  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'
</code></pre>

{% endtab %}

{% tab title="Response" %}
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:

<pre class="language-json"><code class="lang-json">{
  "data": {
    "id": "ABcdeXYzkj",
    "type": "orders",
    "links": { ... },
    "attributes": { ... },
    "relationships": { ... },
    "meta": {
      "created_with_version": "2026-05"
    }
  },
  "meta": {
    "api_version": "2026-05",
    "api_versions": [ "2017-08", "2026-05" ],
    "mode": "test",
    "organization_id": "wBstRPzLrk",
    "trace_id": "d95e207e4358198129f062000650759c3a1b7f4e8d2c6a0b5e9f1d3c7a4b8e20",
<strong>    "deprecations": [
</strong><strong>      {
</strong><strong>        "type": "field",
</strong><strong>        "name": "payment_method_taxable"
</strong><strong>      },
</strong><strong>      {
</strong><strong>        "type": "relationship",
</strong><strong>        "name": "payment_method"
</strong><strong>      },
</strong><strong>      { ... }
</strong><strong>    ]
</strong>  }
}
</code></pre>

{% hint style="info" %}
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.
{% endhint %}
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.commercelayer.io/core/api-versioning.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.