Import API Release Notes

The following features of the Import API achieved the general availability status.

• Import Container
• All Processing States - processing, validationFailed, rejected, unresolved, waitForMasterVariant, imported
• Import Operations
• Import Summaries

Please note that all Import Request endpoints such as Products, Prices, and Categories remain in public beta until further announcement. To learn more about the Import API, please see Best practices as well as the documentation.

As announced on 5 November 2021, we introduced a HTTP status code 400 for errors in all Import API POST endpoints.

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.

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

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.

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.

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

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:

• It is the initial Processing State assigned by default to Import Operations when they are created.
• Import Operations remain in this state if there are missing references to complete the resource import.

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.

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.

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.

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:

• Added the total field to ImportOperationPagedResponse.

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 the staged field to ProductVariantPatch.

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.

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:

• Order Patch endpoint.

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:

• addresses in CustomerImport is now a required field. (It can, however, be an empty array.)
• added CustomerAddress.

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.

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.

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.

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.

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

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.

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.

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:

• New endpoint for Order import Request Order data to be imported.
• New endpoint for querying the status of Order ImportOperations by an ImportSink key Get ImportOperations by an ImportSink key.
• New endpoint for querying the status of Order ImportOperations by its id Get Import operation by its ID.

Customers import:

• New endpoint for Customer import Request customer data to be imported.
• New endpoint for querying the status of Customer ImportOperations by an ImportSink key Get ImportOperations by an ImportSink Key.
• New endpoint for querying the status of Customer ImportOperation by its id Get ImportOperation by its ID.

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.

postman-collection-link