Release Notes

On this page, we will inform you about recent changes in our API.

To stay informed about the latest releases subscribe to the RSS feed

Our release process

In order to release changes as quickly as possible, we don’t use defined release cycles but rather Continuous Integration. This allows us to bring you new features in a few hours and fix problems even faster. Nevertheless all of our releases include only non-breaking changes with the same API version. You can find the exact policy in the API contract.


16 February 2018

GraphQL API surface area was extended and now includes a lot of new query fields and types, as well as experimental mutation support.

Read more…

12 February 2018

It is now possible to capture multiple shipping addresses for one cart. This is done by creating (custom) line item specific shipping addresses. To learn more about this new feature, see our new tutorial.

We added following objects:

We added following fields:

We added following update actions:

We added following error message:

2 February 2018

Customer groups can now be extended with custom fields. This allows users to categorize customer groups any way they want and filter the query result by custom fields.

1 February 2018

So far it was assumed that carts and orders are created by customers themselves only, but to reflect the case of creating carts and orders by the merchants on behalf of customers also, we introduced a new field tracking the origin of a Cart and an Order.

29 January 2018

Discount codes now can be grouped together by assigning one or more groups to an individual discount code. Furthermore, the new Return StateRole can now be used to mark the state of those line items that belong to the return process of an order.

25 January 2018

We published a tutorial about the API Extensions feature we recently released. The tutorial explains the usage of the feature based on two example use cases. In the first example an API Extension is developed that validates a maximum number of items that can be added to the cart. The extension developed in the second example will add a mandatory insurance to the cart if any item in the cart is worth $500 or more. Please check it out.
API Extensions can now return a localized description of the error. If available, the Merchant Center will use the correct localization to display the error.

15 January 2018

When creating a category, the category’s parent can now be set by its user-defined key instead of the platform-generated ID, as it was before. This makes importing of category trees easier since identifiers for all parent categories are known beforehand.

10 January 2018

With API Extensions, you can extend the behavior of the cart API with your business logic. An API Extension gets called after the processing of a create or update request of an API call, but before the result is persisted. The API Extension can validate the object, or apply additional updates to it.
Good use cases for API Extensions are: Validating the content of a cart (e.g. no more than 8 crates of beverages can be ordered at once), calculating custom shipping costs, or adding mandatory items, like insurance, to a cart.

The first part of the new documentation explains how to setup an extension, while the second part describes the input and the possible responses of the extension. The third part details the limits and error cases related to extensions.

20 December 2017

Deliveries can now be given their own addresses. The delivery address is not be confused with the shipping address. An order can only have one shipping address based on which the shipping rate is determined. With delivery address, however, it is possible to capture multiple fulfillment related addresses, e.g. a customer is stocking up on printing paper and has ordered 80 packages printing paper; 20 packages is to be delivered to the main office building, 58 to the warehouse and 2 for his home office. This can be achieved by defining three deliveries for the order, each with their own address.

19 December 2017

We have introduced validity ranges on Discount Codes for limiting the time range in which a code can be applied to a cart. Setting a validity can also help to manage campaigns which are promoted via discount codes, also considering that one code may contain several different cart discounts with varying validity dates.

18 December 2017

We have introduced validity periods on Product Discounts to support discounting a (range of) product(s) within a given time frame. Instead of activating product discounts manually, we now allow promotion planning in advance. Please consider that it can take some time to recalculate product discount values. Many discounts with the same validity values may take up to a few minutes to being live.

15 December 2017

The deliveries of orders can now be amended after creating parcels or deliveries in cases data needs to be added or changed. Corresponding messages have been added, as well as messages for changing the state of the shipment and return shipment to which clients can now subscribe.

6 December 2017

In case the ‘SameForAll’ and ‘Unique’ constraints on attributes of your product types prevent you from extending your products, you can now change them to ‘None’.

5 December 2017

It is now possible to define Cart Discounts by specifying the custom Type of the line items to be discounted or the line items that activate the discount.

4 December 2017

Assets can now be identified by a user-defined key that is unique only within the asset’s container (a product variant or a category). Before only the platform-generated id of the assets could be used to identify them on the platform. Assets can now be placed at a specific position within the asset list when adding them to a ProductVariant or a Category.

1 December 2017

Changes on and deletions of product variants can now be reverted.

30 November 2017

We now provide custom fields on CartDiscounts. This allows users to customize their cart discounts in any way they want and fetch them by filtering on custom fields now supported on the cart discounts endpoint.

17 November 2017

A product variant to be added to a Shopping List and My Shopping List can now be selected by the variant’s SKU. Before the variant had to be selected by product ID and variant ID only.

16 November 2017

The predicate can now be updated or removed on any existing ShippingMethod. Before it could only be set during creation of shipping methods.

15 November 2017

We have introduced the UnitPriceLevel TaxCalculationMode on carts to be able to calculate taxes per unit price and not only per line item as before. The opposite LineItemLevel mode is the default tax calculation mode on the cart so that this new feature does not break any existing application.

2 November 2017

The customer Sign In now always returns a recalculated cart, and allows to update the product data.

  • [API] Customer Sign In has new parameter updateProductData to update name, variant and productType in the line item data.
  • [API] My Customer Profile Sign In has new parameter updateProductData to update name, variant and productType in the line item data.

27 October 2017

We added the capability to use user-defined keys of categories, products and customer groups in predicates for the specification of product and cart discounts. With this it is no longer required to use their platform-generated IDs in the predicates.

26 October 2017

We extended the multi-buy discount feature of type “Buy 4 car tires, get 2 of them 50% off” to CustomLineItems.

25 October 2017

Orders can now be fetched, updated and deleted by providing the user-defined orderNumber instead of the platform-generated id of the order.

24 October 2017

We now support tracking line items on a Parcel. With this new ability, you can define which line items of a Delivery goes into which parcel. Example: An order consists of fresh fruits and meat products. This will be one delivery, but it will have two parcels. One for the fresh fruits and one for the meat products. JVM SDKv1.25.0

  • [API] Added field items to Parcel.
  • [API] Added field items to Add Parcel update action.
  • [API] Changed field items on Add Delivery update action to be optional.

20 October 2017

With dynamic shipping rates it is now possible to dynamically set the price for shipping based on value or the new ShippingRateInput of the cart. For further information on how to use this new feature, please see the tutorial. JVM SDKv1.25.0

19 October 2017

Enum values can now be removed from enum type and localized enum type attribute definitions of product types.
All attributes of all products using those enum keys will be removed in an eventually consistent way. JVM SDKv1.25.0

17 October 2017

We changed the behavior of the Cart’s Recalculate update action.

  • [API] Instead of rejecting update requests to recalculate the cart when any of the line items became invalid (e.g., because corresponding products don’t exist anymore), the relevant items will now be dropped and the recalculation will be executed with only the remaining items.

7 October 2017

We now support CartDiscounts to prevent further application of matching CartDiscounts respecting their sortOrder. Therefore, a new field stackingMode has been added. The former behaviour of always applying all matching discounts is now encapsulated in the default value of stackingMode: Stacking. JVM SDKv1.25.0

6 October 2017

The behavior of CustomLineItems has been improved to behave more similar to regular LineItems when signing in, and when adding a new item.

  • [API] When a customer signs in and the default anonymousCartSignInMode is used, custom line items are merged into the existing customer’s cart.
  • [API] When a custom line item is added and an equivalent one already exists in the cart, the quantity is increased.

29 September 2017

As part of a Beta improvement initiative, the Payment API has been updated deprecating a series of fields. JVM SDKv1.24.0

  • [API] externalId in PaymentDraft, Payment as well as under Update Payment
    This field has been deprecated because the interfaceId can be used for the ID set by the PSP, and the newly introduced key field has taken over the role of externalID.
  • [API] amountAuthorized, amountPaid and amountRefunded in PaymentDraft, Payment as well as under Update Payment
    These fields have been deprecated because their value can be calculated from the total amounts saved in the Transactions.
    • Example 1: Two transactions, one with type:Charge, state:Success and amount:2$ and another one with type:Charge, state:Success and amount:3$. The amountPaid is 5$.
    • Example 2: Two transactions, one with type:Charge, state:Failure and amount:2$ and another one with type:Charge, state:Success and amount:3$. The amountPaid is 3$.
    • Example 3: Two transactions, one with type:Charge, state:Success and amount:3$ and another one with type:Refund, state:Success and amount:2$. The amountPaid is 3$. The amountRefunded is 2$.
  • [API] authorizedUntil in PaymentDraft, Payment as well as under Update Payment
    We learned the field is of little practical value, as it is either not reliably known, or the authorization time is fixed for a PSP.
  • [API] paymentId in PaymentStatusInterfaceCodeSet Message
    This field has been deprecated because the id in the resource field can be used instead.
  • [API] TransactionType previously had uppercase values like AUTHORIZATION, CHARGE etc. These are deprecated.

Furthermore, another TransactionState has been added.

  • [API] The Initial TransactionState has been added. It is used when the PSP has not accepted the transaction yet (including if the PSP has not been contacted yet). The existing Pending state is from now on used when the PSP has accepted the transaction, but it is not completed yet.
    In the future, we will change the default state value in the TransactionDraft to Initial. Do not depend on the default value! Please set the state field explicitly as soon as possible.

28 September 2017

We extended the DiscountCode model to support custom fields. This allows users to categorize discount codes any way they want and fetch them using the predicates on the discount codes endpoint.

27 September 2017

Since the originalPrice field on the line item predicate was duplicating the behavior of the price field, the originalPrice field was removed.

26 September 2017

18 September 2017

We now support getting, updating and deleting Payments by key. This way payments can be identified by the user-defined key instead of the ID the platform has assigned automatically.

15 September 2017

14 September 2017

By using predicates on Shipping Methods, we are empowering our merchants to build their own set of shipping method rules. Dependent on the cart and its content, a merchant can define which shipping methods should be offered during checkout. For further information on how to use this new feature, please see the tutorial.

14 September 2017

We added new endpoints to allow customers to manage their payments with the password flow or with an anonymous session.

11 September 2017

We now removed the limit of cart discounts that are triggered by discount codes. Those discounts were limited to 100 before together with the cart discounts for which no discount code is required.

  • [API] The limit of 100 active CartDiscounts now only applies to cart discounts that do not require a discount code.
  • [API] The number of cart discounts in a DiscountCode is limited to 10.
  • [API] The number of discount codes in a Cart is limited to 10.

8 September 2017

The new cart tax mode ExternalAmount allows to set the totalGross, taxRate and taxPortions fields on cart’s content externally by the client instead of the platform. This is useful in case you prefer to have those values calculated by a third party service.

7 September 2017

Breaking Change
For performance improvements, the “mark-matching-Variants” feature on the Product Projection search endpoint will be disabled by default during the week of September 11th, 2017. If your project does not require the “mark-matching-Variants” feature for product search, no further action is required from your side.

  • [API] If you make use of this feature you now have to enforce it by explicitly setting the markMatchingVariants parameter to true on requests to this endpoint from next week onwards. Please refer to our documentation on how to set the parameter accordingly. PHP SDKv2.0.0

30 August 2017

We added new endpoints to allow Customers to manage their shopping lists with the password flow or with an anonymous session.

24 August 2017

Added an update action to set und unset the anonymous ID of a cart.

22 August 2017

Products can now be filtered by the times they were created or updated latest.

21 August 2017

Added key field to TaxCategories

  • [API] TaxCategories have a new optional field key that allows clients to specify a unique user-specified identifier for the tax category. Keys can be set during creation of the tax category or afterwards by the new update action Set Key. Now tax categories can also be retrieved, updated and deleted by key. JVM SDKv1.22.0 PHP SDKv2.2.0 iOS SDKv0.7.0

18 August 2017

It is now possible to publish only the prices of a product. This allows you to keep other product information you don’t want to publish yet, like updates in the product description, in staged projection while the updated prices will be published already. Product variants to be added to a cart can now be specified by their SKU. Before, the only option was to specify them by their product ID plus variant ID.

17 August 2017

Added key field to Customer

15 August 2017

We added the possibility to use customer group-specific price selection on carts with no customer assigned.

  • [API] CartDraft has a new optional field customerGroup that can be set if customerId is not present. PHP SDKv2.2.0 JVM SDKv1.22.0
  • [API] Added new update action setCustomerGroup to set the customer group to a cart if customerId is not present. PHP SDKv2.2.0 JVM SDKv1.22.0

3 August 2017

We implemented ↗ OAuth2 Token Introspection according to RFC 7662. It allows to determine the active state of an OAuth 2.0 access token and to determine meta-information about this access token, such as the scope.

  • [API] OAuth2 Token Introspection is available on the auth service.
  • [API] The new introspect_oauth_tokens scope allows a client to introspect tokens issued to other clients.

26 July 2017

Added key field to ShippingMethods

  • [API] ShippingMethods have a new optional field key that allows clients to specify a unique user-specified identifier for the shipping method. Keys can be set during creation of the shipping method or afterwards by the new update action Set Key.
    Now shippping methods can also be retrieved, updated and deleted by key. JVM SDKv1.22.0 PHP SDKv2.2.0 iOS SDKv0.6.1

14 July 2017

We introduced a new ‘key’ field on CustomerGroup that can be used to identify a customer group by a user-defined ID in addition to the platform-generated ‘id’.

7 July 2017

After introducing keys on categories, we now extended the update actions for adding and removing products to and from categories. Now it is possible to update products by category key in a same way as by category ID.

29 June 2017

Every ‘manage’ scope for a resource, like Product, Order, Customer and so on, now also implies the respective ‘view’ scope automatically. So far the ‘view’ scope had to be specified explicitly which is not needed anymore.

28 June 2017

We extended the number of supported message buses by adding the Azure Service Bus destination to the subscriptions endpoint.

26 June 2017

For resetting a customer password it is now possible to get the customer by email token. For getting the customer by password token the new endpoint (/password-token={token}) should now be used in favor of the old query parameter (/?token={token}).

21 June 2017

We introduced the new Line Item price mode ‘ExternalPrice’ in which the prices for line items are set externally while eligible cart discounts will be applied. The external prices can now be set during creation of line items.

20 June 2017

The inputHint on AttributeDefinition provides a hint to developers how text-based attribute values should be visually represented in the frontend. The two supported values for this field: SingleLine or MultiLine had to be set in the AttributeDefinitionDraft during creation of the attribute definition so far, but it can now be changed afterwards by introducing a new update action changing the value of this field.

16 June 2017

Added new optional field on customer resource to store information about the salutation of the customers. Added two new cart discount functions that help specifying whether the given predicate should match for at least one or for all line items in the cart.

15 June 2017

We published a tutorial for Order Created Messages as an example for the scenario in which you want to send a notification via email to your customer when an order is created.

14 June 2017

Added and changed messages about changes on products


  • [API] Products can now be added automatically to the cart as free gifts, for example to reward your customers for reaching a predefined cart amount. Free gifts can be added to a cart with the Cart Discount value giftLineItem. The target field must not be set for this value. JVM SDKv1.19.0 PHP SDKv2.1.0
  • [API] LineItems have a new field lineItemMode that can be Standard or GiftLineItem. JVM SDKv1.19.0 PHP SDKv2.1.0 iOS SDKv0.5.9
  • [API] Carts have a new field refusedGifts that is automatically filled when a gift is removed from the cart. JVM SDKv1.19.0 PHP SDKv2.1.0 iOS SDKv0.5.9
  • [API] Categories have a new optional field key that allows clients to specify a unique user-specified identifier for the category. Keys can be set during creation of the category or afterwards by the new update action Set Key. Now categories can also be retrieved, updated and deleted by key. JVM SDKv1.19.0 PHP SDKv2.1.0 iOS SDKv0.5.9





  • [API] Product attributes or custom field names in Cart Discount and Product Discount predicates now also support names that contain dash characters or that are starting with a digit. In such cases, the names need to be escaped with backticks (`).
  • [API] Customers can be referenced by custom fields.




  • [API] The new view_project_settings scope grants access to viewing the project settings. Previously, only the manage_project scope did.




  • [API] ShoppingLists beta can be deleted automatically if they haven’t been modified for the specified amount of days. The field deleteDaysAfterLastModification can be set on the ShoppingListDraft and updated on those. JVM SDKv1.13.0 PHP SDKv2.0.0




  • [API] Active Carts can be deleted automatically if they haven’t been modified for the specified amount of days. The field deleteDaysAfterLastModification beta can be set on the CartDraft and MyCartDraft, and updated on those. If a ChangeSubscription for carts exists, a ResourceDeleted notification will be sent. iOS SDKv0.5.4 PHP SDKv1.7.0 JVM SDKv1.13.0


  • [API] The scope parameter is now optional when requesting an OAuth2 access token. In absence of the scope parameter all the scopes defined for the API client will be granted. We still recommend to explicitly set the scope that your application needs.











  • [API] Subscriptions betaallow you to be notified of new messages or changes via a Message Queue of your choice. They can be used to trigger an asynchronous background process in response to an event on the commercetools platform. PHP SDKv1.5.0 JVM SDKv1.17.0




  • [IMPEX] The ↗ Product Export command now allows specification of the delimiter and the character encoding used in the exported file. Moreover, a full product export is now triggered when no export template is given.














  • [API] Add the option to update product data in a cart with the recalculate update action. [DOC] JVM SDKv1.1.0 PHP SDKv1.2.0


  • [API] Enable to sort by product id for search requests. [DOC] JVM SDKv1.1.0







  • [Admin Center] Users can set a time zone in their profile. All dates in the Admin Center, e.g. on orders and discounts, are shown for the selected timezone. AC







  • [API] The setSku product update action can now be staged. The old setSKU update action without the staging option is still available, but will be deprecated in the future. JVM SDKv1.0.0-RC5 PHP SDKv1.0.0-RC11
  • [Admin Center] It is now possible to add and delete API clients in the Admin Center. When adding a new client, the permissions can be specified. You can now add clients with permissions adapted to a mobile or a single page application for example. AC







  • [API] AttributeDefinition field isSearchable has a new constraint. The max size of a searchable field is now restricted to 10922 characters.

















  • [IMPEX] ↗ Impex Tools and API Playground EU now require a login with the Admin Center account. The account’s permissions for projects are now applied on the API Playground too. Entering client key and client secret are not necessary anymore.


  • [API] LineItem and CustomLineItem got totalPrice and discountedPricePerQuantity properties. Previously available discountedPrice property is now deprecated in favor of discountedPricePerQuantity since it has a higher precision. JVM SDKv1.0.0-M19 PHP SDKv1.0.0-RC7 Node SDK v1.0.0
  • [Admin Center] Allow to set existing Channels on Prices and Stock. AC













  • [Admin Center] Users can now make set attributes searchable when adding the attribute to the productType. AC
  • [Admin Center] We fixed a bug related to updating user profile details. AC


  • [API] Comments feature has been shutdown. PHP SDKv1.0.0-RC3





  • [API] The maximum number of update actions within a single request is now limited to 500. [DOC]






  • [API] Comments can be deleted (Comments endpoint shutdown completely on 18.08.2015). PHP SDKv1.0.0-RC3



  • [API] New attributes can be used when creating a customer: dateOfBirth, companyName, vatId, isEmailVerified, customerGroup and addresses along with defaultBillingAddress and defaultShippingAddress. JVM SDKv1.0.0-M16 PHP SDKv1.0.0-RC1 Node SDK v1.0.0





  • [API] Product prices have an optional validity period. Add new attributes validFrom and validUntil for prices. [DOC] JVM SDKv1.0.0-M14 PHP SDKv1.0.0-RC1 Node SDK v1.0.0



  • [API] Introduction of an official deprecation process. [DOC]


  • [API] Add new attributes maxApplications and maxApplicationsPerCustomer for discountCodes. [DOC]JVM SDKv1.0.0-M17 PHP SDKv1.0.0-RC3 Node SDK v1.0.0
  • [API] Add new DiscountCodeState MaxApplicationReached for carts. [DOC] JVM SDKv1.0.0-M16 PHP SDKv1.0.0-RC2 Node SDK v1.0.0
  • [API] Modify conversion process between a cart and an order to require discountCodes with a DiscountCodeState equals to MatchesCart.
  • [API] Add new error code DiscountCodeNonApplicable for carts. [DOC]





  • [API] Allow to delete carts. [DOC]


  • [API] Add new fields and update actions for customers: dateOfBirth, companyName and vatId. [DOC]


  • [API] Add new update action revertStagedChanges for products. [DOC]


  • [API] Add new suggest endpoint. [DOC]
  • [Documentation] Reworked the documentation for search endpoint and all related resources. [DOC]


  • [API] Query terms for filter and facets are not tokenized anymore.


  • [API] Fix bug that a price cannot be removed if it has a discounted price.
  • [API] Enable to sort by custom attributes for search requests. [DOC]


  • [Admin Center] Add activity state of product discount to overview list.


  • [API] Allow to query information about your project via separate endpoint. [DOC]


  • [Admin Center] Fix bug that projects are not editable right after creation.
  • [API] Fix bug with price update function.
  • [API] Use discounted price for filter actions. [DOC]


  • [API] Enable to sort search results by createdAt and lastModifiedAt. [DOC]
  • [Admin Center] Allow to edit externalId for categories.


  • [Admin Center] Adjust display of boolean attributes.


  • [Admin Center] Improve display of product discounts.


  • [Admin Center] Allow to create and manage product discounts.



  • [Admin Center] New WYSIWYG editor implemented.


  • [API] Enhance product projections with the new value fields createdAt and lastModifiedAt. [DOC]
  • [API] Support = operator for collections to be used with product discount predicates. [DOC]
  • [API] ProductVariant subsets now have to consist of a unique combination of attributes, images, prices and sku(new).


  • [API] Enhance categories with the new value field externalId. [DOC]


  • [API] First implementation of productDiscounts. [DOC]
  • [API] Enhance products to be used with productDiscounts. [DOC]
  • [API] Allow to delete customerGroups. [DOC]
  • [Admin Center] Allow to delete customerGroups from the MC.


  • [Admin Center] Allow to delete tax categories and zones from the MC.
  • [Admin Center] Improve validation of money values (attribute / price).


  • [Admin Center] Allow to create boolean attributes and use them in variant view.


  • [API] Allow to delete tax categories. [DOC]
  • [API] Allow to delete zones. [DOC]


  • [API] Allow to set customerNumber and orderNumber if the values are not set yet. [DOC] [DOC]
  • [Admin Center] Allow to set customerNumber and orderNumber in customers / orders detail view.
  • [Admin Center] Allow to set externalId in customers detail view.
  • [Admin Center] Allow to set the price and freeAbove for shippingMethods to 0.


  • [Admin Center] Allow to filter createdAt per date-only and optionally with time (orders and customer search).


  • [Admin Center] Redesign of the “Delivery” UI for orders.
  • [API] Add a new attribute type for custom attributes of product types: boolean [DOC].


  • [API] Add the possibility to add a delivery and parcels in one call. [DOC]



  • [Admin Center] Version upgrade for integration.
  • [Admin Center] Confirmation required for creating new ENUM/LENUM values.
  • [Admin Center] Automatically redirect to original URL after login when session expired before.


  • [Admin Center] Optimised Dashboard views.
  • [Admin Center] Adjust WYSIWYG Editor initialization and parsing rules.


  • [Admin Center] Support new dashboard for “Import & Export” menu.


  • [Admin Center] Adjust time gap for revenue calculation on dashboard.
  • [Admin Center] Integration of adding values to existing enumeration keys.
  • [Admin Center] Enable to set enumeration key and label.


  • [Admin Center] Introduce MC Settings (included for now enabling/disabling of HTML-Editor mode).


  • [API] Increased possible length for GET request.


  • [ Connector] Pass orderNumber as reference_number to

  • [Documentation] Add information for connector


  • [API] Add new field “additionalAddressInfo” to Address


  • [Admin Center] Display channel key at SyncInfo in OrderView


  • [Admin Center] Add support for printing shipping notes as PDF using an HTML template