Import API Releases

A new error code, NewMasterVariantAdditionNotAllowed, is returned when an import operation fails because a newly imported Product Variant is set as the Master Variant (isMasterVariant=true).

Only an existing Product Variant can be set as the Master Variant. To resolve the error, you can either update the existing Master Variant or create a new Product Variant and then set it as the Master Variant.

Changes:

• [API] Added the NewMasterVariantAdditionNotAllowed error code.

The Import API is now available on Azure in Europe, in addition to the existing Regions available on Azure (Virginia, North America), Google Cloud Platform (GCP), and Amazon Web Services (AWS). For more information about hosts, see Hosts.

As previously announced, we have now removed the publish field on EmbeddedPriceImport and ProductVariantImport.

Use the staged field to control whether the imported data should be applied to the current and/or staged representation of the Product.

The Import API is now available on AWS in North America and Europe, in addition to the existing Regions available on Google Cloud Platform (GCP) and Azure. For more information about hosts, see Hosts and Authorization.

The Import API is now available on Azure in North America, in addition to the existing Regions available on Google Cloud Platform (GCP). For more information about hosts, see Hosts.

To simplify the process of importing Embedded Prices and Product Variants, we have added the staged field to EmbeddedPriceImport and ProductVariantImport. With this new staged field you can control whether the imported data should be applied to the current and/or staged representation of the Product to update.

The staged field replaces the publish field, which is now deprecated and will be removed on 1 August 2024.

This change brings the Import API in line with the HTTP API by using the same fields for the same purpose. If you are using the publish field to import Embedded Prices and Product Variants, you should use staged instead and adjust the value based on your use case.

Changes:

• [API] Added staged to EmbeddedPriceImport.
• [API] Added staged to ProductVariantImport.
• [API] Deprecated publish field on EmbeddedPriceImport.
• [API] Deprecated publish field on ProductVariantImport.

As previously announced, we will change the behavior of the publish field when importing Product data. This change helps you to prevent accidental publishing of Products, which can negatively impact customer satisfaction and brand reputation due to poor/incomplete product information, or can lead to the premature exposure of products to customers.

As this may break existing implementations, we have postponed the implementation to 1 August 2024. This gives you additional time to prepare for this change.

Please reach out to your contact at commercetools if you have any questions.

On 1 August 2024*, we will change the behavior of the publish field when importing Product data. The following changes will reduce the complexity of importing Product data, and will prevent unintended publishing:

• You can only use the publish field to publish or unpublish Products when importing Products or Product drafts.
• When importing Embedded Prices, Product Variants, or Product Variant Patches:
  • If a Product is currently unpublished, then it will not be published even if publish is true.
  • The Product's current projection will not be replaced by the staged projection.

*The original date of this change was 22 April 2024. We have extended the date to give users additional time to adapt to this change.

We have added the Import Discount Codes endpoint to the Import API. This new feature allows you to bulk import Discount Codes to your Composable Commerce Project.

You can now send us the whole Discount Code snapshot and we will create/update resources in your Project by calculating the delta.

Changes:

• [API] Added Import Discount Codes endpoint.

We introduced the product field on ProductVariantPatch. This field allows you to reference the Product which contains the Product Variant, and batches import operations to help prevent concurrency errors.

Changes:

• [Import API] Added the product field to ProductVariantPatch.

As announced before, we have now changed the key field on EmbeddedPriceDraftImport to be required.

You must now include a value for key in EmbeddedPriceDraftImport when importing Embedded Prices using the Import Product drafts endpoint.

Changes:

• [API] Changed key of EmbeddedPriceDraftImport to be required on the Import Product drafts endpoint.

The addresses field in CustomerImport on the Import Customers endpoint has changed from required to optional. This change aligns the Import API with the HTTP API and makes it easier for users to create and update Customers with the Import API.

As announced before, the key field on EmbeddedPriceDraftImport is changing from optional to required.

The effective date of this change has been extended to 31 July 2023. This extension provides users with additional time to make necessary updates to accommodate this change.

We have added the Type endpoint to the Import API. This new feature allows you to bulk import Types to your Composable Commerce Project for modeling Custom Fields.

You can now send us the whole Type snapshot and we will create/update the entry in your Project by calculating the delta.

Changes:

• [API] Added Type Import endpoint.

To enhance the performance and reliability of the Import API, we are changing the key field on EmbeddedPriceDraftImport from optional to required.

This change will take effect on 31 July 2023*. From this date, you must include a key when importing Prices using EmbeddedPriceDraftImport.

*The original date of this change was 11 July 2023. The date was extended to provide users with additional time to make necessary updates to accommodate this change.

You can now import Customers with an AuthenticationMode to determine if they should use a password or external authentication. The addition of AuthenticationMode also means that passwords are no longer mandatory when importing Customers.

Order Import can also now include Custom Fields on their shippingAddress, and Parcels fields.

State is also now available for import in Order Import.

These additions provide more options and greater flexibility when importing Customers and Orders.

Changes:

• [API] Added authenticationMode to CustomerImport on the Import Customers endpoint.

• [API] Added Custom Fields to shippingAddress in OrderImport on the Import Orders endpoint.

• [API] Added Custom Fields to Parcel in OrderImport on the Import Orders endpoint.

• [API] Added state to OrderImport on the Import Orders endpoint.

As we have recently introduced a key field on Embedded Prices, we have aligned pattern and length constraints accordingly so that there are no inconsistencies for imported Prices.

Values for the key field in EmbeddedPriceDraftImport, EmbeddedPriceImport, and StandalonePriceImport should now match the pattern ^[A-Za-z0-9_-]+$ and be 2-256 characters in length. The key value will be validated when processing import requests with the following objects:

• Product draft import endpoints having Price keys.
• StandalonePriceImport on Importing Standalone Prices.
• EmbeddedPriceImport on Importing Embedded Prices.

The Import Orders endpoint now supports referencing Stores by key using StoreKeyReference.

Changes:

• [API] Added StoreKeyReference on the Import Orders endpoint.

The Standalone Price Import endpoint has been added to the Import API, enabling the bulk import of Standalone Price.

You can now:

• Send us the whole StandalonePrice snapshot and we will create/update the entry in your Project by calculating the delta.

Using the Standalone Prices endpoint is the same as using other Import API endpoints. For more information:

• View the best practices guide for the Import API.
• Discover how Import Containers work.

The Product Draft endpoint only supports Embedded Prices. Standalone Prices must be imported separately using Standalone Price endpoint.

Changes:

• [API] Added Standalone Price Import endpoint.

The Import Orders endpoint now supports Custom Fields for Line Items.

Changes:

• [API] Added Custom Fields to LineItemImportDraft on the Import Orders endpoint.

The Import Customers endpoint now supports Custom Fields for Customer addresses.

Changes:

• [API] Added Custom Fields to CustomerAddress on the Import Customers endpoint.

You can now set the PriceMode of Products using the Product import and Product draft import endpoints.

Standalone Prices recently achieved general availability, enabling you to use Standalone Prices with the Import API. It is convenient to set the PriceMode at the Product level when creating or updating Products using the Import API.

Consult the Import API reference documentation to learn how to set the PriceMode when importing (creating or updating) a Product:

• Set Price mode using the Product import endpoint.
• Set Price mode using the Product draft import endpoint.

The Inventory endpoint has been added to the Import API, enabling the bulk import of Inventory Entries.

You can now:

• Send us the whole InventoryEntry snapshot and we will create/update the entry in your Project by calculating the delta.
• Use the Inventory endpoint to schedule hourly/daily/nightly/weekly bulk inventory import processes.

Using the Inventory endpoint is the same as using other Import API endpoints. For more information:

• View the best practices guide for the Import API.
• Discover how Import Containers work.

Changes:

• [API] Added Inventory Import endpoint.

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 that supports 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. Additionally, 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. Multiple sorting is also allowed for up to three fields.

Sorting in the Import API works the same way as in the commercetools Composable Commerce HTTP APIs. Please refer to our existing documentation for the commercetools Composable Commerce API for more details.

Introduced support to the key field in EmbeddedPriceDraftImport as an optional input.

It is now possible to keep track of the EmbeddedPriceDraftImports that are sent in ProductDraftImportRequests.

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

To create or update Orders in bulk, use the Importing Orders endpoint. This new feature calls Order API 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, use Importing Customers endpoint. This new feature calls Customer API endpoints such as Create Customer for creating Customers and Update Customer for updating existing Customers.

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 Composable Commerce using an 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