# API specification

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](https://docs.commercelayer.io/core/sparse-fieldsets), resource linking, [filtering](https://docs.commercelayer.io/core/filtering-data), [sorting](https://docs.commercelayer.io/core/sorting-results), [pagination](https://docs.commercelayer.io/core/pagination), 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](https://app.gitbook.com/s/XD42JVYENWrharWaLF3W/#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="authentication" %}
[authentication](https://docs.commercelayer.io/core/authentication)
{% 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.

### 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](https://docs.commercelayer.io/core/api-credentials): **sales channel**, **integration**, **webapp**. Which one to use depends on your specific need. You can leverage our [how-tos](https://app.gitbook.com/o/-Lfu_B3DKew-kvoEWzTk/s/-Lk-ezuDClaMavTqnRi0/) 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](https://docs.commercelayer.io/core/exporting-resources) most of the resources (SKUs, prices, stock, etc.) from your test env and [import](https://docs.commercelayer.io/core/importing-resources) 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://app.gitbook.com/o/-Lfu_B3DKew-kvoEWzTk/s/8DjTu5pfPzXTm6rzaAmr/).