HTTP API Contract

As new features are released regularly for the commercetools platform, we have an API contract to ensure a smooth evolution. This document presents the different contracts of the API.


The commercetools platform uses Continuous Delivery to be able to deploy updates multiple times a day. This means that we don’t have fixed release cycles, but instead bring features live for you as soon as they are ready. It also allows us to correct any possible issues very fast. Nevertheless, keeping track of all improvements and changes might not be possible for all our users at all times. Thus, as part of our API contract, we ensure that:

  • No values or fields will be changed or deleted in the same API version
  • Every change within the same API version only includes additional information
    • new fields and values within an existing object
    • new messages for the Messages API
    • new API endpoints
    • required fields becoming optional

For more information, see ↗ this blog post.

Last update: September 10th 2018


Please be aware that if a client sends additional fields, these can conflict with future new platform field names, causing runtime errors. Avoiding this is in the responsibility of the client.

Beta features

Some features are tagged as beta. This means that the APIs related to that feature can be subject to change and they should be used carefully in production. Nevertheless, they are stable and can be used to play around or test new functionalities. During the beta phase, feedback is highly appreciated as it helps to iron out all problems and make sure that the feature is really useful. Once the feature is no longer tagged as such, we will announce it in the release notes.


As the commercetools platform evolves, some features are superseded by better implementations and should not be used anymore. The goal of our deprecation process is, at runtime, to communicate with users if they happen to use such deprecated features. To achieve this in a non breaking fashion, the commercetools platform uses an additional custom HTTP header called X-DEPRECATION-NOTICE with a specific message relative to the deprecation.


"X-DEPRECATION-NOTICE" : "The usage of lower-cased search on variants.price.currencyCode is deprecated"

SSL/TLS Lifetime

In order to keep connections to the API secure at all times, it is necessary to periodically renew SSL/TLS certificates and also replace them when adapting to newer security policies. We try to keep those modifications to a minimum. In general, we target a maxmimum of one certificate renewal per year. However, if security issues are found within any aspect of the encryption algorithms in use, we reserve the right to replace certificates more quickly.


To assure good performance for every project on the platform, the API imposes limits on certain parameters and objects.

JSON document size

Every JSON document persisted through any API endpoint should not exceed 16 megabytes.
Any update action on existing resources that would make documents break that limit will not succeed.

Field content size

For performance reasons, the maximum size of a searchable field within an AttributeDefinition can not exceed 10922 characters. Non searchable fields are only limited by the overall JSON document size.


A Slug must match the pattern [a-zA-Z0-9_-]{2,256}, hence they are limited to 256 characters.

Update actions per request

For performance reasons, the maximum number of update actions within a single request is limited to 500.


Within a query, up to 500 elements can be fetched. When using pagination, the maximum offset is 100000.

Search and Facets

For performance reasons, the maximum size of a searchable field within an AttributeDefinition can not exceed 10922 characters. The number of terms per facet is limited to 200.

Within a search request, up to 500 elements can be fetched. In pagination, the maximum offset is 100000.


A maximum number of 700 prices can be specified on a ProductVariant.

Product Discounts

The maximum number of ProductDiscounts that can be active at the same time is 500.

Cart Discounts

The number of active CartDiscounts that do not require a discount code (isActive=true and requiresDiscountCode=false) is limited to 100.

Shopping Lists

A ShoppingList can contain up to 100 line items and and up to 100 text line items.


The number of discount codes in a Cart is limited to 10.

Discount Codes

The number of cart discounts in a DiscountCode is limited to 10.


If a project has more than 100 product types, then GraphQL extensions are not generated and product attributes are not accessible via the GraphQL API.