BETA

Overview

What is the Import API?

The Import API uploads data to the commercetools platform. Its asynchronous design is suitable to sync a large amount of resources from external systems into commercetools projects.

Import API scheme

The arrows in the diagram indicate the data flow. The data to be imported needs to be one of the supported Import Resource Types.

Why shall I use the Import API?

The Import API has the following advantages:

  • Asynchronous
    You can send bulk data at once, and your systems can do something else while your data is imported asynchronously.

  • Resource specific
    You can separately import products, product variants, and prices.

  • Automatic dependency handling
    The Import API automatically handles data dependencies such as the parental relations of categories.

  • API First
    Unlike other CLI tools and UI tools, it gives you better integration opportunity with your modern application infrastructure.

How to use the Import API

We introduce the following abstract data type for an expository purpose:

ImportRequest

An ImportRequest stands for the abstract data type that encompasses CategoryImportRequest, ProductTypeImportRequest, ProductImportRequest, ProductDraftImportRequest, ProductVariantImportRequest, PriceImportRequest, OrderImportRequest, and CustomerImportRequest.

Generalities

To use the Import API, you need to create an ImportSink. An ImportSink can be thought of as a temporarily storage for data to be imported. You can add import operations to an ImportSink by creating an ImportRequest. The operations are then processed and validated. To track the progress of import operations (known as ProcessingStates), you can call the get endpoint of ImportOperations or ImportSummaries.

Import API Workflow

The Import API uses a particular workflow.

Workflow

  1. Create an ImportSink for the resource type you would like to import. Keep in mind that an ImportSink can only import a single resource type. If you want to import more than one type of data, you need to create ImportSinks separate for each data type. The ImportResourceType enum lists all supported resource data types.
  2. Next, Create an Import Request for the resource type you would like to import. For example, for importing categories you would need to Create an import request specific to categories.
  3. After sending an ImportRequest, the Import API returns a list of import operation statuses, which are given in terms of ProcessingStates. You can then poll the ImportSink to check the status of each ImportOperation.
  4. The ImportSink processes each operation. It validates the structure of the operation and any references in the operation, and updates the operation's state. For more information, see State Flow.
  5. If successful, the import operation's state is Imported and changes are imported to commercetools.
  6. During the import process, it is possible to get an aggregated summary of all the ImportOperation states by fetching an ImportSummary.
  7. If the ImportSummary shows that some ImportOperations have ended up in state ValidationFailed or Rejected, it is also possible to see the errors for each ImportOperation by querying them by the respective states. Here is an example of how to query ProductDraftImports by state, the same goes for other resources.

You only need to set up an ImportSink for a data type once. If you already have an ImportSink for a data type, you can send it ImportRequests at any time.