API specification

Basic info about endpoints, resources, credentials, and environments

Commerce Layer exposes a fast REST API that lets you add ecommerce to your favorite tech stack.

Commerce Layer API is 100% compliant with the JSON API specification (v1.0). It supports compound documents, sparse fieldsets, resource linking, filtering, sorting, pagination, and more. The JSON API community has shared some client libraries that can help you get started.

All the strings passed to the API must be UTF-8 encoded. Date-time parameters must comply with the ISO 8601 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.

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.

Authentication

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

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

Authentication

Base endpoint

Once you have a valid token, all API requests must be made over HTTPS to the following base endpoint:

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 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 protocol to manage clients' authorization. It defines three types of API credentials: sales channel, integration, webapp. Which one to use depends on your specific need. You can leverage our 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.

Working in test mode is free forever. You can try Commerce Layer in test mode as long as you need to.

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.

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 most of the resources (SKUs, prices, stock, etc.) from your test env and import them to the live one. If you import orders, you will be charged for the placed ones, according to the pricing plan you subscribed to.

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

Open-source projects and developer tools

JS SDK, CLI, and 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 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.