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.


19 September 2018

We are announcing that Subscriptions have been taken out of Beta. After releasing several enhancements over the last weeks, this is being done with no further changes to the functionality of Subscriptions.

17 September 2018

We are announcing that the Shopping List API has been taken out of Beta. This is being done without any changes or enhancements to the API’s current functionality.

14 September 2018

User-provided identifiers are identifiers that are not set by the API (like the id field is), but provided by the API user (like the key or orderNumber fields). In particular the design goal of the key field is to allow client applications to only use the key field, and ignore the API-provided id field.

This release progresses towards the design goal by adding the key field among other user-provided identifiers into data structures commonly used in asynchronous processing by Subscriptions and the Messages Endpoint.

13 September 2018

The following ten resourceTypeIds are now supported by Change Subscriptions:

  • cart-discount
  • channel
  • discount-code
  • extension
  • product-discount
  • shopping-list
  • subscription
  • state
  • tax-category
  • type

12 September 2018

Before, the cart decided, based on the update actions, whether to update the product prices and tax rates. We’ve received feedback that this was unpredictable and confusing.

Therefore, the cart now updates the product prices and tax rates, along with discounts and the shipping info, on every update. No change to your code is necessary, but you may remove superfluous Recalculate update actions (if they don’t update the product data).

  • [API] The Update Cart section now contains a description of the updates
  • [API] The description of the Recalculate update action has been changed to reflect the two remaining use cases for it

7 September 2018

You can now apply financial changes after an Order has been placed with OrderEdits. OrderEdits are wrappers that capture OrderUpdateActions which can create a preview of changes and apply them to the Order.

The OrderEdit tutorial shows some examples how edits can be performed.

This feature is in beta beta so we do not guarantee that the API is in its final shape.

4 September 2018

We have introduced new error codes that should help you analyzing the root cause of ‘Bad Request’ type errors by giving more specific error messages.

We have enriched an existing error code with additional information to be more specific on the error cause.

We have added the error code that can occur when removing enum values from an attribute definitions that are still in use by products.

4 September 2018

We are updating our SSL setup to only support TLS 1.2 for all encrypted connections. Starting October 2018, we will drop support for older SSL/TLS versions. For exact details on the SSL/TLS setup that we will support refer to the Security section of our general HTTP API documentation.

For application testing, we offer temporary URLs that already support the new setup. These URLs are available now but only until end of September when the changes go into effect. The test URLs are:

For EU:


For US:


Please note again that these URLs are for testing purposes only and will be shut down as soon as our main setup has changed.

The SSL setup change as outlined here will go into effect on Monday, October 1st, 2018 between 9 and 11 am (UTC).

28 August 2018

It is now possible to set the validFrom and validUntil values for CartDiscounts and DiscountCode in the same update action. We also added support for these update actions to the GraphQL API.

27 August 2018

Query for States is now supported on the GraphQL API too.

  • [GraphQL API] Type Query was extended:
    • Field states was added to Query type.
    • Field state was added to Query type.
  • [DOC] Fix documentation of State:
    • The field name is optional.
    • The field description is optional.
  • [DOC] Fix documentation of StateDraft:

27 August 2018

You can now be notified about deletion of orders that have been created for test purposes, for instance.

27 August 2018

We have extended the support for Reference Expansion to ShippingMethod-related endpoints.

14 August 2018

  • [GraphQL API] The following types were added in the GraphQL schema: AddCartCustomLineItem, AddCartDiscountCode, AddCartItemShippingAddress, AddCartLineItem, AddCartPayment, AddCartShoppingList, AddMyCartLineItem, ApplyCartDeltaToCustomLineItemShippingDetailsTargets, ApplyCartDeltaToLineItemShippingDetailsTargets, BaseMoneyInput, Cart, CartDraft, CartOrigin, CartQueryResult, CartState, CartUpdateAction, ChangeCartCustomLineItemMoney, ChangeCartCustomLineItemQuantity, ChangeCartLineItemQuantity, ChangeCartTaxCalculationMode, ChangeCartTaxMode, ChangeCartTaxRoundingMode, ChangeMyCartTaxMode, ClassificationShippingRateInput, ClassificationShippingRateInputDraft, CustomLineItem, CustomLineItemDraft, Delivery, DeliveryItem, DiscountCodeInfo, DiscountCodeState, DiscountedLineItemPortion, DiscountedLineItemPrice, DiscountedLineItemPriceForQuantity, ExternalLineItemTotalPriceDraft, ExternalTaxAmountDraft, ExternalTaxRateDraft, HighPrecisionMoneyInput, InventoryMode, ItemShippingDetails, ItemShippingDetailsDraft, ItemShippingTarget, ItemState, LineItem, LineItemDraft, LineItemMode, LineItemPriceMode, MyCartDraft, MyCartUpdateAction, MyLineItemDraft, Parcel, ParcelMeasurements, PaymentInfo, RecalculateCart, RemoveCartCustomLineItem, RemoveCartDiscountCode, RemoveCartItemShippingAddress, RemoveCartLineItem, RemoveCartPayment, RoundingMode, ScoreShippingRateInput, ScoreShippingRateInputDraft, SetCartAnonymousId, SetCartBillingAddress, SetCartCountry, SetCartCustomField, SetCartCustomLineItemCustomField, SetCartCustomLineItemCustomType, SetCartCustomLineItemShippingDetails, SetCartCustomLineItemTaxAmount, SetCartCustomLineItemTaxRate, SetCartCustomShippingMethod, SetCartCustomType, SetCartCustomerEmail, SetCartCustomerGroup, SetCartCustomerId, SetCartDeleteDaysAfterLastModification, SetCartLineItemCustomField, SetCartLineItemCustomType, SetCartLineItemPrice, SetCartLineItemShippingDetails, SetCartLineItemTaxAmount, SetCartLineItemTaxRate, SetCartLineItemTotalPrice, SetCartLocale, SetCartShippingAddress, SetCartShippingAddressAndCustomShippingMethod, SetCartShippingAddressAndShippingMethod, SetCartShippingMethod, SetCartShippingMethodTaxAmount, SetCartShippingMethodTaxRate, SetCartShippingRateInput, SetCartTotalTax, SetCustomerGroup, SetCustomerNumber, SetMyCartShippingMethod, ShippingInfo, ShippingMethodState, ShippingRateInput, ShippingRateInputDraft, ShippingTargetDraft, TaxCalculationMode, TaxMode, TaxPortion, TaxPortionDraft, TaxedItemPrice, TaxedPrice, TrackingData, UpdateCartItemShippingAddress.
  • [GraphQL API] The following types were removed from the GraphQL schema: SetCustomerCustomerGroup, SetCustomerCustomerNumber.
  • [GraphQL API] Type Me was changed:
    • Field carts was added to Me type
    • Field activeCart was added to Me type
    • Field cart was added to Me type
  • [GraphQL API] Type Query was changed:
    • Field carts was added to Query type
    • Field cart was added to Query type
    • Field customerActiveCart was added to Query type
  • [GraphQL API] Type CustomerSignInResult was changed:
    • Field cart was added to CustomerSignInResult type
  • [GraphQL API] Type CustomerUpdateAction was changed:
    • CustomerUpdateAction.setCustomerGroup input field type changed from SetCustomerCustomerGroup to SetCustomerGroup
    • CustomerUpdateAction.setCustomerNumber input field type changed from SetCustomerCustomerNumber to SetCustomerNumber
  • [GraphQL API] Type Mutation was changed:
    • Field deleteCart was added to Mutation type
    • Field deleteMyCart was added to Mutation type
    • Field createMyCart was added to Mutation type
    • Field updateMyCart was added to Mutation type
    • Field updateCart was added to Mutation type
    • Field replicateCart was added to Mutation type
    • Field createCart was added to Mutation type

Read more…

9 August 2018

Due to low adption in our customer base, we have removed IronMQ from the Subscription documentation. We continue to support IronMQ for customers that are already using it.

8 August 2018

Subscriptions now have a HealthStatus allowing you to monitor the health of a subscription with a tool of your choice. For production-critical queues, we recommend to set up an automatic alert.

With the new update action changeDestination, a ConfigurationError can be fixed (common causes are deleting the destination queue, deleting the access credentials, or removing the permission to push messages into the queue).

We have modified our handling of delivery failures caused by ConfigurationErrors:

  • A production project has up to 24 hours to fix the configuration
  • A development or staging project has up to an hour to fix the configuration

After that, we’ll drop the messages, and will not attempt to deliver further messages. In this case, the subscription gets the status ConfigurationErrorDeliveryStopped. For more information, see the updated Delivery Guarantees.

7 August 2018

The product discount limit was increased to 500.

3 August 2018

Both Subscriptions and API Extensions can contain access secrets, e.g. to allow the commercetools platform to place a message into a queue, or to invoke an AWS Lambda function. When retrieving an access secret via the commercetools platform API, it is now hidden (except for the last 4 characters).

This change should help you to keep your access secrets secure. As noted in both Subscriptions and API Extensions, we recommend to create access credentials that only have the permission to put a message into the specific message queue, or only invoke the particular API Extension.

1 August 2018

It is now possible to set the Customer ID on an existing Order. A respective Message is now generated upon such changes so that clients can subscribe to it, if interested.

20 July 2018

  • [GraphQL API] Following types were added in the GraphQL schema: ChangeCustomerGroupName, CustomerGroupDraft, CustomerGroupUpdateAction, SetCustomerGroupCustomField, SetCustomerGroupCustomType, SetCustomerGroupKey.
  • [GraphQL API] Type CustomerGroup was changed:
    • Field customFieldsRaw was added to CustomerGroup type
  • [GraphQL API] Type Mutation was changed:
    • Field updateCustomerGroup was added to Mutation type
    • Field deleteCustomerGroup was added to Mutation type
    • Field createCustomerGroup was added to Mutation type

Read more…

18 July 2018

The Subscriptions support ↗ Google Cloud Pub/Sub as a destination. It can be used both as a pull-queue, and to push messages to e.g. Google Cloud Functions or HTTP endpoints (webhooks). PHP SDKv2.5.0

18 July 2018

18 July 2018

The Change Subscription payloads now have the field modifiedAt. PHP SDKv2.5.0

18 July 2018

Added setValidFromAndUntil to product discount update methods. PHP SDKv2.5.0

12 July 2018

  • [GraphQL API] The following types were added in the GraphQL schema: AddCustomerAddress, AddCustomerBillingAddressId, AddCustomerShippingAddressId, Address, AddressContactInfo, AddressInput, AnonymousCartSignInMode, ChangeCustomerAddress, ChangeCustomerEmail, Customer, CustomerQueryResult, CustomerSignInDraft, CustomerSignInResult, CustomerSignMeInDraft, CustomerSignMeUpDraft, CustomerSignUpDraft, CustomerToken, CustomerUpdateAction, Me, MyCustomerUpdateAction, RemoveCustomerAddress, RemoveCustomerBillingAddressId, RemoveCustomerShippingAddressId, SetCustomerCompanyName, SetCustomerCustomField, SetCustomerCustomType, SetCustomerCustomerGroup, SetCustomerCustomerNumber, SetCustomerDateOfBirth, SetCustomerDefaultBillingAddress, SetCustomerDefaultShippingAddress, SetCustomerExternalId, SetCustomerFirstName, SetCustomerKey, SetCustomerLastName, SetCustomerLocale, SetCustomerMiddleName, SetCustomerSalutation, SetCustomerTitle, SetCustomerVatId.
  • [GraphQL API] Type Query was changed:
    • Field customer was added to Query type
    • Field customers was added to Query type
    • Field me was added to Query type
  • [GraphQL API] Type Mutation was changed:
    • Field customerCreatePasswordResetToken was added to Mutation type
    • Field customerCreateEmailVerificationToken was added to Mutation type
    • Field customerSignMeUp was added to Mutation type
    • Field customerConfirmEmail was added to Mutation type
    • Field deleteMyCustomer was added to Mutation type
    • Field deleteCustomer was added to Mutation type
    • Field customerResetMyPassword was added to Mutation type
    • Field updateMyCustomer was added to Mutation type
    • Field customerSignMeIn was added to Mutation type
    • Field updateCustomer was added to Mutation type
    • Field customerChangeMyPassword was added to Mutation type
    • Field customerChangePassword was added to Mutation type
    • Field customerResetPassword was added to Mutation type
    • Field customerConfirmMyEmail was added to Mutation type
    • Field customerSignIn was added to Mutation type
    • Field customerSignUp was added to Mutation type

Read more…

12 July 2018

CloudEvents is a specification for describing event data in a common way. CloudEvents seeks to ease event declaration and delivery across services, platforms and beyond. It is hosted by the Cloud Native Computing Foundation.

CloudEvents is a new effort and it’s still under active development. The format is versioned, and we do not plan to offer long-term support for outdated versions yet. Therefore, CloudEvents is currently only offered in Preview, with the goal to give feedback to the CloudEvents working group.

Support for ↗ Azure Event Grid has been added, which offers native support to filter and route CloudEvents. EventGrid can be used to push messages to Azure Functions, HTTP endpoints (webhooks), and several other Azure tools.

  • [API] Added Format to the Subscriptions API. The CloudEvents format can be used with all of the existing destinations.
  • [API] Added the Azure Event Grid Destination. It can only be used with CloudEvents.

11 July 2018

  • [GraphQL API] The following types were added in the GraphQL schema: AddInventoryEntryQuantity, ChangeInventoryEntryQuantity, InventoryEntry, InventoryEntryDraft, InventoryEntryQueryResult, InventoryEntryUpdateAction, RemoveInventoryEntryQuantity, SetInventoryEntryCustomField, SetInventoryEntryCustomType, SetInventoryEntryExpectedDelivery, SetInventoryEntryRestockableInDays, SetInventoryEntrySupplyChannel.
  • [GraphQL API] Type Query was changed:
    • Field inventoryEntries was added to Query type
    • Field inventoryEntry was added to Query type
  • [GraphQL API] Type Mutation was changed:
    • Field deleteInventoryEntry was added to Mutation type
    • Field createInventoryEntry was added to Mutation type
    • Field updateInventoryEntry was added to Mutation type

Read more…

28 June 2018

We made the error codes for creation and updates of ProductType more specific to ease error handling for you.

  • [API] Added more specific error messages. Please find details in the Errors documentation.

19 June 2018

The GraphQL API now allows you to filter for those ProductVariants that have images or that are available in stock.

  • [GraphQL API] Added filtering parameters isOnStock, stockChannelIds and hasImages to ProductData.variants and ProductData.allVariants.

13 June 2018

A category’s parent can now be set using its user-defined key instead of the platform-generated ID.

8 June 2018

When the payload of a message subscription had to be dropped (usually due to a size constraint of the destination message queue), the reason as well as the value of the type field is placed into the notification. PHP SDKv2.5.0

6 June 2018

The shipmentState can now be set when creating an order from a cart. Before, it was only settable by an update action, requiring an additional API call. PHP SDKv2.5.0

1 June 2018

Based on customer feedback we changed the behavior of the StackingMode StopAfterThisDiscount.

  • [API] The StackingMode StopAfterThisDiscount now continues with further discounts if the discount could not be applied because the CartDiscountTarget did not match. Previously, the application of further discounts was stopped even if the target condition was not fulfilled.

31 May 2018

As part of a Beta improvement initiative, we’ve announced breaking changes to the Payment API in September. The changes have been applied now, and the Payment API is out of Beta.

31 May 2018

Custom fields on category and product price are now supported on GraphQL endpoint.

31 May 2018

We have published a tutorial about how commercetools fulfills the requirements of the General Data Protection Regulations.

30 May 2018

Mutations for the CartDiscount and ProductDiscount are now supported on the GraphQL endpoint.

  • [GraphQL API] Following types were added in the GraphQL schema:
    • AbsoluteDiscountValueInput, CartDiscountDraft, CartDiscountTargetInput, CartDiscountUpdateAction, CartDiscountValueInput, ChangeCartDiscountCartPredicate, ChangeCartDiscountIsActive, ChangeCartDiscountName, ChangeCartDiscountRequiresDiscountCode, ChangeCartDiscountSortOrder, ChangeCartDiscountStackingMode, ChangeCartDiscountTarget, ChangeCartDiscountValue, CustomLineItemsTargetInput, ExternalDiscountValueInput, GiftLineItemValueInput, LineItemsTargetInput, MoneyInput, MultiBuyCustomLineItemsTargetInput, MultiBuyLineItemsTargetInput, ProductDiscountDraft, ProductDiscountValueInput, RelativeDiscountValueInput, SetCartDiscountCustomField, SetCartDiscountCustomType, SetCartDiscountDescription, SetCartDiscountValidFrom, SetCartDiscountValidUntil, ShippingTargetInput.
  • [GraphQL API] Type ProductDiscount was changed:
    • ProductDiscount type description is changed
  • [GraphQL API] Type Mutation was changed:
    • Field updateProductDiscount was added to Mutation type
    • Field updateCartDiscount was added to Mutation type
    • Field deleteProductDiscount was added to Mutation type
    • Field createProductDiscount was added to Mutation type
    • Field createCartDiscount was added to Mutation type
    • Field deleteCartDiscount was added to Mutation type

Read more…

24 May 2018

In some countries, particularly the ones in the European Union, you are required by law (such as the GDPR) to erase personal data of a customer on request, also known as “Right to be Forgotten”. PHP SDKv2.5.0

A default DELETE request may not clean up all data, both visible at the HTTP API layer (e.g. personal data may be part of messages) and invisible (the commercetools platform internally keeps logs for some time, to reconstruct data in case of faulty system behavior).

Endpoints that store personal data therefore offer a parameter for DELETE requests called dataErasure. If set to true, the commercetools platform guarantees that all personal data related to the particular object, including invisible data, is erased, in compliance with the GDPR. You are, however, responsible for identifying and deleting all objects that belong to a customer, and deleting them.

The parameter is available for:

Personal data MUST NOT be stored in objects other than the ones listed above.

9 May 2018

For those businesses whose product prices require a higher precision than the currently offered cent amount, we have extended our pricing model to additionally support sub-cents for ProductVariant prices. In order to support this, a new money type HighPrecisionMoney was introduced. High precision money usage can be interchanged with regular money usage everywhere where BaseMoney is used. PHP SDKv2.5.0

  • [API] BaseMoney - base polymorphic type which supports cent and high precision at the same time.
  • [API] Money - added fractionDigits and type fields.
  • [API] HighPrecisionMoney - supports definition of sub-cent amounts.
  • Following types have been updated to support high precision prices while keeping everything compatible with cent precision Money:

2 May 2018

The user-defined key can now be used on Carts and Customers endpoints to identify a Customer Group.

27 April 2018

  • [GraphQL API] Added new field DiscountCode.applicationCount.
  • [GraphQL API] Product variant info now includes availability information. Since the list of availability per sales channel can get quite big there is a support for pagination and inclusion and exclusion of sales channels.

Read more…

25 April 2018

A Correlation ID is a unique identifier of a single action, allowing to trace the action across multiple systems.

  • [API] The API accepts a client-provided Correlation ID if sent with the X-Correlation-ID HTTP header
  • [API] If the client does not provide one, the API generates one and the response contains the X-Correlation-ID HTTP header

20 April 2018

It is now possible to provide an Authorization Header when creating a new HTTP API Extension. The Authorization header will be set to the headerValue when the HTTP API Extension is called. PHP SDKv2.5.0

To get started with API Extensions in general, please read the tutorial.

19 April 2018

When line items of an order should be shipped to different addresses those shipping details can now be updated on orders.
We added the following update actions to Order to manage multiple shipping addresses: JVM SDKv1.31.0PHP SDKv2.5.0

Please find more about usage of multiple shipping addresses in our tutorial.

17 April 2018

You can now create API Extensions natively with AWS Lambda. The AWS Lambda functions are invoked directly (and do not need to go through the AWS API Gateway). JVM SDKv1.31.0PHP SDKv2.5.0

To get started with API Extensions in general, please read the tutorial.

29 March 2018

The new matching ProductDiscount endpoint can be used to simulate which product discounts would be applied if a product variant had a specified price. JVM SDKv1.31.0PHP SDKv2.5.0

23 March 2018

You can now extend the behavior of the Orders API with your business logic with the help of API Extensions. An API Extension gets called after the processing of a create or update request of an API call but before the order is persisted. The API Extension can validate the order or apply additional updates to it. It can, for example, validate that an order with the given configuration can be created, automatically add an order number, or change states. JVM SDKv1.31.0PHP SDKv2.5.0

To get started with API Extensions in general, please read the tutorial.

9 March 2018

We have introduced two update actions on the ProductType resource: one to update the name of an attribute definition, and one to update the key of any enum value. JVM SDKv1.30.0PHP SDKv2.4.0

2 March 2018

You can now extend the behavior of the Payment API and the Customer API with your business logic with the help of API Extensions. 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. It can, for example, validate that a payment in the given configuration can be processed, or trigger actions with the Payment Service Provider (PSP). Or it can validate that a customer’s account details don’t look fraudulent, or set a customer group based on the email address. JVM SDKv1.30.0PHP SDKv2.5.0

To get started with API Extensions, you can read the tutorial.

2 March 2018

The cart predicate language has been simplified.

  • [API] A boolean value is now a valid predicate. E.g. if a cart discount should match all carts, the predicate true is now sufficient. Previously, one had to write 1 = 1 or true = true.
  • [API] A boolean function is now a valid predicate. E.g. lineItemExists(...) is now sufficient. Previously, one had to write lineItemExists(...) = true.

2 March 2018

We now support creating a new cart by replicating an existing cart or order. JVM SDKv1.30.0PHP SDKv2.4.0

1 March 2018

We have introduced new messages about updates on the Customer resource. With the introduction of these messages, you can now get notified about changes to specific fields for the Customer. Previously, it was only possible to get the generic change messages with the ChangeSubscription on the Customer resource. JVM SDKv1.30.0PHP SDKv2.4.0

Furthermore, Customer Group has been added as supported resource for ChangeSubscription.

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. JVM SDKv1.29.0PHP SDKv2.5.0

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. JVM SDKv1.29.0PHP SDKv2.3.0

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. JVM SDKv1.29.0PHP SDKv2.3.0

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. JVM SDKv1.29.0PHP SDKv2.3.0

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. JVM SDKv1.28.0

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. JVM SDKv1.28.0PHP SDKv2.5.0

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. JVM SDKv1.27.0PHP SDKv2.3.0

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. JVM SDKv1.28.0PHP SDKv2.3.0

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. JVM SDKv1.28.0PHP SDKv2.3.0

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. JVM SDKv1.28.0PHP SDKv2.3.0

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’. JVM SDKv1.27.0PHP SDKv2.3.0

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. JVM SDKv1.27.0PHP SDKv2.3.0

1 December 2017

Changes on and deletions of product variants can now be reverted. JVM SDKv1.27.0PHP SDKv2.3.0

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. JVM SDKv1.27.0PHP SDKv2.3.0

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. JVM SDKv1.26.0PHP SDKv2.3.0

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. JVM SDKv1.26.0PHP SDKv2.3.0

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. JVM SDKv1.26.0PHP SDKv2.3.0

2 November 2017

The customer Sign In now always returns a recalculated cart, and allows to update the product data. JVM SDKv1.26.0PHP SDKv2.3.0

  • [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. PHP SDKv2.4.0

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. JVM SDKv1.26.0PHP SDKv2.3.0

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 PHP SDKv2.3.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 PHP SDKv2.3.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 PHP SDKv2.4.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 PHP SDKv2.3.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 PHP SDKv2.3.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. PHP SDKv2.3.0

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. PHP SDKv2.3.0

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. PHP SDKv2.2.0

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



  • [API] Add encoding “Content-Type: application/json” as optional HTTP Request header