Import API Release Notes

Error status code 400 for POST request

5 November 2021

Effective on 7 December 2021, Import API POST endpoints will respond with the HTTP status code 400 for errors. Currently you receive the status code 200 if one or more resources in your Import Request have errors.

For the users to be able to prepare for this change, we will update the SDK before the actual change to the API takes place. The next SDK release will reflect this change. Before 7 December 2021, this new part of the SDK cannot be used.


Unpublish Products via Import API

22 October 2021
Product Catalog

You can now unpublish a Product using Product and ProductDraft import endpoints by setting the publish field to false.

Custom Objects in Custom Fields and Attributes is now supported.

17 September 2021
CustomizationProduct Catalog

Reference Type Custom Fields of type key-value-document are now supported. This enables you to import Custom Objects in Custom Fields. Custom Fields of this type can be imported for every resource for which the platform supports this type of Custom Fields. Attributes (of ProductVariant) of key-value-document Reference Type are also supported. Please see CustomObjectKeyReference for more information.


New Processing State structure introduced

7 September 2021

As announced on 9 August 2021, we introduced a new Processing State structure. Additinally, the Processing State values are now spelled in the (lower) camel case to better align with the HTTP API.

The processing of your Import Request itself should not be impacted by this change; however, if you have some sort of monitoring using Processing States, you need to change the code. We apologize for the inconvenience this may cause.

The following changes were made:

  • Introduced a new Processing State processing. This is the initial state assigned to an Import Operation.
  • The unresolved state will no longer be the initial state.
  • The unresolved state continues to be used (but exclusively) as the state to indicate missing references.
  • key of ProductVariantDraftImport is now mandatory.

Renaming Import Sink to Import Container and restructuring URLs.

30 August 2021
DeprecationImport ContainersProduct Catalog

The Import Sink is deprecated and replaced with the Import Container. This deprecation is for the name change purpose, and all functionalities and behaviors of the Import Sink are succeeded by the Import Container without change. The name change, however, is accompanied by the restructuring of the URL patterns toward the REST standard. The changed URLs are listed below. The old deprecated URLs and the Import Sink endpoint stay available until 30 November 2021. They will be removed thereafter. We encourage the switch to the Import Container and the new URLs.

The following changes were made:

  • Import Sink is deprecated and Import Container was introduced. This is a name change. All functionalities and behaviors of the Import Sink is succeeded by the Import Container.
  • key is now mandatory in ProductVariantDraftImport.
  • Resource import POST request (for example, Import Categories and Import ProductTypes)
    • previous: /{projectKey}/{resourceType}/importSinkKey={importSinkKey}
    • current: /{projectKey}/{resourceType}/importContainerKey/{importContainerKey}
  • Monitoring endpoints
    • Get ImportSummary
      • previous: /{projectKey}/import-summaries/importSinkKey={importSinkKey}
      • current: /{projectKey}/import-containers/{importContainerKey}/import-summaries
    • Get ImportOperation by ID
      • previous: /{projectKey}/{resourceType}/importSinkKey={importSinkKey}/import-operations/{id}
      • current: /{projectKey}/import-operations/{id}
    • Query ImportOperations by Import Container ID
      • previous: /{projectKey}/{resourceType}/importSinkKey={importSinkKey}/import-operations
      • current: /{projectKey}/import-containers/{importContainerKey}/import-operations

Introducing a new Processing State structure

9 August 2021

Effective from 6 September 2021, we will introduce a new Processing State. The new Processing State called Processing will be added as a default state. The Unresolved state will be reserved exclusively for unresolved references.

This will be a breaking change from the business logic perspective although we are only changing the meaning of an existing state without removing it. The processing of your import request itself should not be impacted by this change; however, if you have some sort of monitoring using Processing States, you will need to change the code. We apologize for the possible inconvenience.

Currently, the Unresolved state has the following meaning:

On 6 September 2021, we will introduce a new state called Processing and the following changes will take place:

  • Processing will be the new default Processing State assigned to Import Operations when they are created.
  • The Unresolved state will no longer be the initial state.
  • The Unresolved state continues to be used (but exclusively) as the state to indicate missing references. A user's action will be required in this state to fix the missing references.

Unresolved references can now be discovered with debug mode

23 July 2021

We have introduced a debug mode for the Query Import Operation endpoints for all resource types. This mode makes it easier for you to find out what the reason is for the Import Operation being in the Unresolved Processing State by listing which references exactly could not be resolved.

When setting the debug query parameter to true you will find the list of unresolved references in the respective additional field in the query response as shown in the following example.


ImportSink is no longer specific to a ResourceType

6 July 2021

Since an ImportSink is no longer specific to an ImportResourceType it is no longer mandatory to specify the ImportResourceType when creating an ImportSink.

The following change was made:

  • Made the resourceType field on the ImportSinkDraft optional.

Total field added to ImportOperationPagedResponse

5 July 2021

Pagination through the query results for Import Operations is now fully supported by populating the total number of results in the paged query response.

The following change was made:

Staged field was added to ProductVariantPatch

28 June 2021
Product CatalogPatches

Added the staged field to ProductVariantPatch. The field can be used to specify whether to apply ProductVariant updates to the current projection of a Product.

The following change was made:

Added sort query parameter for ImportSinks

23 June 2021

The query endpoint for ImportSinks now supports the sort parameter.

The following changes were made:

  • Added sort query parameter to the query ImportSinks endpoint.
  • The query parameters limit and offset are now optional at the query ImportSinks endpoint.

Introducing Order Patch endpoint

7 June 2021

Introduced Order Patch endpoint. It should be used to update ReturnInfo, Parcel, and Delivery of an existing Order. The updates can be many in a single request or as one update per request.

The following endpoint was added:

Key as the identifier of Address at Customer Import endpoint

11 May 2021

The Customer Import endpoint is enabled again. We have made the changes below. You will receive proper 2XX responses for valid API requests. We apologize for the inconvenience we may have caused.

The Customers Import endpoint now uses key of an Address as a mandatory identifier for Addresses, and id is no longer a supported identifier. Said differently, the addresses field in CustomerImport now takes the CustomerAddress type, replacing the previous Address.

The following changes were made:

Added restrictions on unsupported fields in payloads

27 April 2021

Every endpoint of the Import API now accepts only supported fields in input payloads. Any Import API POST request with an unsupported field input will fail with an InvalidFieldError.


Customer Import endpoint is temporarily under maintenance

27 April 2021

The Customers Import endpoint of the Import API is currently under maintenance.

You currently receive a 503 Service Unavailable error if you try to access the Customers Import endpoint. We are working on a fix to bring this endpoint back to work and we will inform you in a further release note again as soon as the fix is deployed. We apologize for any inconvenience this may cause.

Key field is removed from OrderImport

23 April 2021

The key field is deprecated from OrderImport of the Import API. The existing field orderNumber is now a required identifier for any Order import or update. The following changes were made at the Order Import endpoint:

  • Deprecated the key field in OrderImport.
  • The existing (previously optional) field orderNumber is now required.

Fixed validation on Products POST endpoint

22 December 2020
Resolved Issue
Product Catalog

The Products POST endpoint now only accepts fields that are valid according to the ProductImport representation. Before, you could find errors only in the ImportOperation and ImportSummary in case of invalid fields on ProductImports.

Added endpoints for Product Variant Patches

18 December 2020
Product CatalogPatches

Now you are able to update more than one ProductVariants belonging to different or the same Products with several small Patches.


Added sort query parameter in GET endpoints

18 December 2020

In all Get ImportOperations by an ImportSink Key endpoints, we now support an additional query parameter sort, with which you can sort the createdAt and lastModifiedAt fields with sort options asc (default) or desc. Multipe sorting is also allowed up to three fields.

Sorting in the Import API works as in the Platform API. Please refer to our existing documentation for the Platfrom API for more details.

Added key field to PriceDraftImport

12 November 2020

Introduced support to the key field in PriceDraftImport as an optional input. It is now possible to keep track of the PriceDraftImports that are sent in ProductDraftImportRequests.

Added endpoints for Order and Customer imports

1 October 2020

The Import API now supports two additional resource types, Orders and Customers.

To create or update bulk Orders in the commercetools platform, use the Importing Orders endpoint. This new feature calls platform endpoints such as Create an Order by Import for creating new orders and Update Order for updating existing orders.

To create or update customers in bulk in the commercetools platform, use Importing Customers endpoint. This new feature calls platform endpoints such as Create Customer for creating new cutomers and Update Customer for updating existing cutomers.

The new feature includes the following changes.

Orders import:

Customers import:

Public beta release of Import API

3 September 2020

Recently we introduced Import API to allow you to import your large amount of data into commercetools using API first approach.

While the previous solutions for data importing still being relevant, we launch the import API as a beta solution and intend to understand your data import use cases. Import API is in public beta but it supports almost all the major resource types such as Product, Category, Product Type, Variants, and Prices.

You can try new import API using Postman collection or you can use our latest SDKs to implement solutions programmatically.


Filter by Date
Filter By Topics