Import API Releases

Information about recent changes to the Import API.

Added 'product' field to ProductVariantPatch

29 September 2023
Announcement
Product Catalog

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:

Changed EmbeddedPriceDraftImport key field to be required

31 July 2023
Announcement
Product Catalog

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:

Addresses field is now optional on Customer Import

18 July 2023
Feature
Customers

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.

Extended the date when the EmbeddedPriceDraftImport key field changes from optional to required

11 July 2023
Announcement
Pricing and Discounts

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.

Added Type import endpoint

12 May 2023
Feature
Customization

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:

EmbeddedPriceDraftImport key field changing from optional to required

11 April 2023
Announcement
Pricing and Discounts

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.

Added support for AuthenticationMode in Customer import and support for Custom Fields and State in Order import fields.

1 March 2023
Feature
OrdersCustomers

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:

Introducing pattern and length validation for keys of Embedded Prices and Standalone Prices

14 December 2022
Enhancement
Pricing and Discounts

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:

Order import now supports Store key reference

18 October 2022
Enhancement
Orders

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

Changes:

Introducing the Standalone Price import endpoint

26 September 2022
Feature
Pricing and Discounts

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:

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

Changes:

Order import now supports Custom Fields on Line Items

26 August 2022
Enhancement
Orders

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

Changes:

Customer import now supports Custom Fields on addresses

22 August 2022
Enhancement
Customers

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

Changes:

PriceMode can now be set on Products using the Import API

21 July 2022
Feature
Pricing and DiscountsProduct Catalog

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:

Introducing the Inventory import endpoint

30 June 2022
Feature
Product Catalog

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:

Changes:

Core part of the Import API achieves general availability status.

21 December 2021
Announcement
Import ContainersMonitoring

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

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.

Error status code 400 for POST request

7 December 2021
Enhancement
General

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

Read more...

Error status code 400 for POST request

5 November 2021
Announcement
General

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.

Read more...

Unpublish Products via Import API

22 October 2021
Enhancement
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
Enhancement
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 that supports Custom Fields. Attributes (of ProductVariant) of key-value-document Reference Type are also supported. Please see CustomObjectKeyReference for more information.

Read more...

New Processing State structure introduced

7 September 2021
Enhancement
General

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.

Renaming Import Sink to Import Container and restructuring URLs.

30 August 2021
Enhancement
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
Announcement
General

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
Enhancement
Monitoring

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.

Read more...

ImportSink is no longer specific to a ResourceType

6 July 2021
Enhancement

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
Enhancement
Monitoring

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
Enhancement
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
Enhancement

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
Feature
Orders

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
Enhancement
Customers

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
Enhancement

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.

Read more...

Customer Import endpoint is temporarily under maintenance

27 April 2021
Announcement
Customers

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
Enhancement
OrdersDeprecation

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
Feature
Product CatalogPatches

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

Read more...

Added sort query parameter in GET endpoints

18 December 2020
Enhancement
General

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.

Added key field to PriceDraftImport

12 November 2020
Enhancement

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.

Added endpoints for Order and Customer imports

1 October 2020
Feature
OrdersCustomers

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.

Public beta release of Import API

3 September 2020
Feature

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

Releases
Filter by date
Filter by topics