> 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-specification.md).

# API specification

Basic info about endpoints, resources, credentials, and environments

Commerce Layer exposes a fast [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) API that lets you add ecommerce to your favorite tech stack.

Commerce Layer API is 100% compliant with the [JSON API](http://jsonapi.org/format/) specification (v1.0). It supports compound documents, [sparse fieldsets](/core/sparse-fieldsets.md), resource linking, [filtering](/core/filtering-data.md), [sorting](/core/sorting-results.md), [pagination](/core/pagination.md), and more. The JSON API community has shared some [client libraries](http://jsonapi.org/implementations/#client-libraries) that can help you get started.

{% hint style="warning" %}
All the strings passed to the API must be [UTF-8](https://en.wikipedia.org/wiki/UTF-8) encoded. Date-time parameters must comply with the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard (complete date plus hours, minutes, and seconds — expressed in UTC, with `Z` as a special UTC designator). You can change the date visualization on the Dashboard by setting the desired timezone from your account profile.
{% endhint %}

The guide that follows is your reference for all the operations that you can perform on the API resources and contains all the information you need to get a comprehensive overview of how it works.

{% hint style="success" icon="robot" %}
Commerce Layer documentation is [LLM-ready](/readme.md#llm-friendly)! To feed the knowledge base into your own LLM, read [this file](https://docs.commercelayer.io/llms.txt).
{% endhint %}

### Authentication

All API requests must be authenticated. To get a valid access token you need to send a `POST` request to the following endpoint:

```http
https://auth.commercelayer.io/oauth/token
```

{% content-ref url="/pages/-LgCGPTjMSTg9sVBpFDk" %}
[Authentication](/core/authentication.md)
{% endcontent-ref %}

### Base endpoint

Once you have a valid token, all API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure) to the following base endpoint:

```http
https://yourdomain.commercelayer.io
```

Where `yourdomain` is the unique subdomain of your organization.

### Versioning

The Commerce Layer Core API is versioned to support the gradual rollout of new capabilities while maintaining backward compatibility for existing integrations:

* Resources introduced by a new version are only available starting from that version.
* Resources removed by a new version remain temporarily available but are explicitly [deprecated](#deprecation-warnings) in the API response, and will eventually become unavailable in future versions.

`2017-08` is the default version, used whenever the request URL doesn't specify one, so existing integrations keep working unchanged. Newer versions are opt-in: you only get them by requesting them explicitly.

{% content-ref url="/pages/dkJa52Ciu7VQ1vYUpQG1" %}
[API versioning](/core/api-versioning.md)
{% endcontent-ref %}

### Meta information

Some meta information is automatically provided in the API response. This information is split into two distinct levels:

* [Document-level meta](#document-level-meta)
* [Resource-level meta](#resource-level-meta)

#### Document-level meta

The `meta` object at the document level is present on every successful response, whether it returns a single resource or a collection. Error responses may also include it:

<pre class="language-json"><code class="lang-json">{
  "data": [ ... ],
<strong>  "meta": { ... }
</strong>}
</code></pre>

It contains context about the current request:

<table><thead><tr><th width="180">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>api_version</code></strong></td><td>The API version used for this request.</td></tr><tr><td><strong><code>api_versions</code></strong></td><td>The list of API versions supported by the requested resource.</td></tr><tr><td><strong><code>mode</code></strong></td><td>Whether the request is in <strong>test</strong> or <strong>live</strong> mode.</td></tr><tr><td><strong><code>organization_id</code></strong></td><td>The organization the request belongs to.</td></tr><tr><td><strong><code>trace_id</code></strong></td><td>A unique identifier assigned to the request, carried across all layers and included in every log entry. Use it to correlate all logs belonging to the same request, reconstruct its path across services, and troubleshoot issues without guesswork.</td></tr><tr><td><strong><code>deprecations</code></strong></td><td>The list of <a href="#deprecation-warnings">deprecation warnings</a> (omitted when none).</td></tr></tbody></table>

If the response refers to a paginated list of records, the document-level meta is enriched with additional pagination info:

<table><thead><tr><th width="220">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>record_count</code></strong></td><td>The total number of records matching the request.</td></tr><tr><td><strong><code>page_count</code></strong></td><td>The total number of pages available.</td></tr><tr><td><strong><code>page_number</code></strong></td><td>The current page number.</td></tr><tr><td><strong><code>page_size</code></strong></td><td>The number of records per page.</td></tr><tr><td><strong><code>record_count_estimated</code></strong></td><td>Set to <code>true</code> when <code>record_count</code> and <code>page_count</code> are estimates rather than exact counts (omitted otherwise — see <a href="/core/pagination.md">pagination</a>).</td></tr></tbody></table>

{% content-ref url="/pages/-LgSlVz3\_Y6DS2SktOCP" %}
[Pagination](/core/pagination.md)
{% endcontent-ref %}

**Deprecation warnings**

When a response includes deprecation warnings, they appear as a list under `meta.deprecations` at the document level. Each entry describes what is deprecated:

<table><thead><tr><th width="140">Field</th><th width="140" data-type="checkbox">Always present</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>type</code></strong></td><td>true</td><td>What is deprecated: <code>resource</code>, <code>field</code>, or <code>relationship</code>.</td></tr><tr><td><strong><code>name</code></strong></td><td>true</td><td>The name of the deprecated item.</td></tr><tr><td><strong><code>removed_in</code></strong></td><td>false</td><td>The version when it will be hard-removed.</td></tr><tr><td><strong><code>more_info</code></strong></td><td>false</td><td>Additional context or a link to the documentation.</td></tr></tbody></table>

{% hint style="info" %}
Warnings are deduplicated — the same item will not appear twice in the same response even if accessed multiple times.
{% endhint %}

#### Resource-level meta

The `meta` object at the resource level is present on every resource object appearing in the response, whether it returns a single resource or a collection:

<pre class="language-json"><code class="lang-json">{
  "data": [
    {
      "...": "other resource attributes",
<strong>      "meta": { ... }
</strong>    },
    {
      "...": "other resource attributes",
<strong>      "meta": { ... }
</strong>    }
  ],
  "meta": { ... }
}
</code></pre>

At the moment it contains one field only:

<table><thead><tr><th width="200">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>created_with_version</code></strong></td><td>The API version that was active when this resource was created. Resources created before API versioning was introduced report the version of the current request instead.</td></tr></tbody></table>

{% hint style="info" %}
The information above stays at resource level because it describes the record itself rather than the current request, except for records created before API versioning was introduced (see above).
{% endhint %}

### Core resources

Commerce Layer commerce API features **400+ endpoints**. Check our [API reference](https://docs.commercelayer.io/api-reference/) for the complete and updated list of all the core resources, in detail. For each single resource you will find:

* The **resource** object and its fields, attributes, and relationships.
* The allowed **CRUD** operations you can perform on the related endpoint with basic examples of the request/response format.

### Credentials

Commerce Layer implements the industry-standard [OAuth 2.0](https://oauth.net/2/) protocol to manage clients' authorization. It defines three types of [API credentials](/core/api-credentials.md): **sales channel**, **integration**, **webapp**. Which one to use depends on your specific need. You can leverage our [how-tos](https://docs.commercelayer.io/how-tos/) to get started with the most popular use cases.

### Environments

For each organization, you can work either in **test mode** (default) or **live mode**.

{% hint style="info" %}
Working in test mode is **free forever**. You can try Commerce Layer in test mode as long as you need to.
{% endhint %}

Test mode also provides you with a development environment after the go-live. All API calls are identical between the two environments. Use test or live API credentials to make the switch.

{% hint style="warning" %}
Switching to live mode means opening a completely **new** (empty) environment where you can get real orders, with different credentials to access. If you want to replicate your test setup in the live environment you can [export](/core/exporting-resources.md) most of the resources (SKUs, prices, stock, etc.) from your test env and [import](/core/importing-resources.md) them to the live one. If you import orders, you will be charged for the placed ones, according to the [pricing plan](https://commercelayer.io/pricing) you subscribed to.
{% endhint %}

{% hint style="success" %}
Test and live mode are two different, separate environments. Once enabled live mode, switching from one to another doesn't affect any functionality of the single env (e.g. switching back from live to test **does not switch off** your live environment and doesn't cause any issue to your live website that will continue working as expected).
{% endhint %}

### Open-source projects and developer tools

[JS SDK](https://github.com/commercelayer/commercelayer-sdk), [CLI](https://github.com/commercelayer/commercelayer-cli), and [React components](https://github.com/commercelayer/commercelayer-react-components) are available as open-source projects. More libraries and SDKs for the most popular languages are coming soon. We also provide a tested and constantly updated [OpenAPI schema](https://data.commercelayer.app/schemas/openapi.json) you can leverage to build mock servers, auto-generate code, and implement contract testing.

### Changelog

To stay up-to-date with any changes we make on Commerce Layer APIs, apps, and open-source projects (including versioning, product releases, new features, and general improvements), make sure to check our [changelog](https://docs.commercelayer.io/changelog/).


---

# 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-specification.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.