Frequently Asked Questions about the commercetools platform

Haven’t found your question? Check questions tagged commercetools on StackOverflow, ask a missing question there or contact our support team.

Where can I see my online shop?

The commercetools platform provides the backend of E-Commerce applications through an HTTP API. Since the platform allows you to build whatever application you need, from ‘classic’ online shops to mobile applications, market places and so on, we leave the implementation and hosting of your online shop to you.
To help you with building your online shop we provide some template shops you can use as examples. Please find them among other useful open source software, such as SDKs and command line tools for data import, export and synchronization, on our Developer Tools page.

What do I need the slug for?

Slugs are human-readable identifiers usually used in online shops as deep-link URL to the related product. Slugs provide a “nicer” link to the products compared to randomly generated strings as long as they are unique across the project.

The search index will be recreated after new product attributes have been added to the project. This process can take a few minutes dependent on the number of products in the project.
You can also tell the platform to refresh the product search in the ↗ Admin Center EU (and the ↗ Admin Center US ) like shown below:

Refresh Product Search

What is the difference between search and query?

The Product Projection Search endpoint is the most performant choice for product lookup since it allows quick responses due to Elastic Search support. In case Reference Expansion is desired one of the query options below needs to be applied.

Product Projections query:

The Query Product Projections method requires the backend to go through the product database in order to check the products against the query predicates. Thus, the query requested from a shop-front-end can take much longer compared to a search request. The amount of data to be submitted is lower compared to the ‘product query’ method below. Reference Expansion is supported by this method.

Product query:

The Query Products method is the preferred option for shop-backends since the representations for the staged as well as the current Product Projection are returned. Reference Expansion is supported by this method.

How to make anonymous carts persistent?

Anonymous cart is by default persistent until it gets merged (upon customer’s sign in or sign up) with customer’s cart. You need to store the ID of the anonymous Cart on your end. Fetch the particular cart via Get Cart by ID operation.

How to make customer’s carts persistent?

The customer’s cart is persistent by default for an unlimited time. Customer’s cart can be retrieved via:

How to realize multibuy discounts like Buy 6 Get 1 Free?

Let’s say, you sell wine with the SKU “XYZ” with the price of 4.99 € for a bottle, but customers get one bottle for free when they buy at least six bottles of it.
Multibuy dicounts like this can be realized with an absolute CartDiscountValue of the price of one bottle:

  "value": {
    "type": "absolute",
    "money": [{
      "centAmount": 499,
      "currencyCode": "EUR"

The minimum quantity of six bottles in the cart (that is needed to get the discount) will be specified in the Cart predicate:

  "cartPredicate": "lineItemCount(sku=\"XYZ\") >= 6"

With the CartDiscountTarget you’ll specify which LineItem will be discounted. This will be the wine with SKU “XYZ”:

  "target": {
   "type": "lineItems",
   "predicate": "sku=\"XYZ\""

Use those parameters when Creating the CartDiscount or adjust them to your needs.

How can I store payment information in the commercetools platform?

We recently introduced a Payment endpoint to the commercetools platform that allows you to manage payment-related information. Although this feature is still in beta you are encouraged to use it and to provide feedback on our ↗ Support Portal that we’ll take into account to improve the feature.
If you don’t want to use beta features you can achieve something similar with following two proven ways:

Alternative 1: Inside the Order, but just IDs:

Use special SyncInfo entries per payment (or payment transaction) that can be added to Order object via an Update Action. To separate them from other synchronization information, you should add a special Channel Object per payment provider and payment method and reference that in the SyncInfo. The externalId of the SyncInfo should then be used for the transaction identifier given to you by the payment provider.

Alternative 2: Separate from Order with freely modeled data:

Use CustomObjects and define a container dedicated to order payments (e.g. “order-payment”). Use the CTP Order ID as the object key. Then you can use an endpoint like /{ProjectKey}/custom-objects/order-payment/{OrderId} for your payment related operations.

How can I integrate a payment provider with the commercetools platform?

Currently there are no prepackaged PSP adapters for the commercetools platform, so it is left to the shop developer to implement the integration with a payment provider. We are going start an adapter program soon that makes use of the payment object introduced recently.

Are there integrations available with Amazon, ebay, Rakuten and price comparison sites?

Integrations with those sites are currently not available in the commercetools platform, but you can use services like brickfox, Tradebyte, Channelpilot, ChannelAdvisor or ProductsUp for realizing this.

How does Staging and Publishing / Push to Production of Product Data work in the commercetools platform?

In the commercetools platform, you always have 2 versions of the Product Data - current and staged. You can use this to change the product data without changing the running Production website, and preview the changes before you make them live. In the commercetools platform, no data is actually copied back and forth between different instances or databases, but only between the current and staged field of the ProductCatalogData. This means that you can run a staging site for preview purpose and your production site from one single commercetools platform project. It is also best practice to only make changes in the staged version of your product data.

All changes are usually made in the staged version of the data to not impact a running website, and then published using the Publish API Call. Both versions are present in the Product resource within the ProductCatalogData. If you use Product Search API and the Product Projection Resource, you only get either the staged or the current version, depending on whether you set the staged parameter to true or false (default = false). You can learn whether your product has been published and has staged changes by observing the flags published and hasStagedChanges that are part of the ProductCatalogData field.

What is the “Master Variant” and what can I use it for?

In the commercetools platform, the ProductVariant is supposed to be the only sellable entity, but not the abstract Product itself. Therefore, the first role of the master variant is to ensure that the product has at least 1 variant that can be purchased. This means that even a simple product always has one, and your shop implementation logic does not have to deal with any polymorphism where you have to consider a Product and a ProductVariant to be added to a cart.

Furthermore, in our default shop implementation such as Sunrise, we use the master variant as our preferred variant (i.e. with best selling color or image) on product overview, search or product detail page, if no other parameters to determine the suitable variant are given. So you can control which color and size for instance is shown and selected by default, if no other criteria to select a variant to display are given.

Third, the variants have an implicit order that is governed by the variant’s id field. The master variant always has id set to 1, making it the first in the order of variants.

Fourth, in the Admin Center, you can use the Master Variant to update attributes with the SameForAll constraint. The result is that it’s automatically set on all product variants, so you do not have to manually set the attribute on all variants to comply to the constraint. When updating product data through the HTTP API, you can use the setAttributesInAllVariants Update Action.

Are stacked discounts supported / can I apply more than one discount to a cart?

Short answer: yes.

Long answer: This is the only supported discount mode in the commercetools platform at the moment. All applicable discounts will be applied to the cart, if the conditions are met. This includes ProductDiscounts, which are reflected already in the discounted Price of a ProductVariant, and any implicit CartDiscount that matches the given parameters for Cart, Customer and more that will be automatically added to the cart, and any explicit discount that is triggered by a DiscountCode. This means if you want to avoid discounts to stack up, you need to make sure that the predicates and discount conditions such as validFrom and validUntil time period exclude each others.