Documentation

API overview

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 of the Import Resource Types can be imported.

Advantages

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

ImportRequest

An ImportRequest is the data type that is sent in a request body to create or update resources in a commercetools Project. An ImportRequest may contain maximum of 20 resources to import. ImportRequests are resource-specific.

Generalities

An ImportContainer can be thought of as the entry point of data and the place where the data is temporarily stored while the asynchronous import process is carried out. An import process can be initiated by posting an ImportRequest to one of the resource-specific endpoints for import. In response, an ImportResponse is returned, which is the list of the ID's and validation statuses of the newly created ImportOperations. Here, an ImportOperation can be said to be a status report of each import resource. During the import, you can monitor the import status by calling the Get ImportOperation, Query ImportOperations, or Get ImportSummary endpoints. (The first method tells you the status of each import resource, the second the status of all import resources in a specific Import Container, and the third describes the status of an Import Container by the number of resources in each Processing State.)

Import API Workflow

The Import API employs the following workflow.

Workflow

  1. Create an ImportContainer.
  2. Next, create an ImportRequest and post it to a resource-specific endpoint for import (for example, Import Categories). This initiates an import process.
  3. After sending the ImportRequest, the Import API returns an ImportResponse, the list of newly created ImportOperations and their validation statuses.
  4. During the import process, it is possible to get an aggregated summary (called an ImportSummary) of all the ImportOperations associated with a specific ImportContainer by calling Get ImportSummary.
  5. The Import API validates the import data structures and updates state of ImportOperations. For more information, see Processing State.
  6. If the import is successful, state of the ImportOperations becomes "imported". The corresponding resource is now imported into the commercetools Project.
  7. Suppose the ImportSummary shows that some ImportOperations ended up in the state validationFailed or rejected. You can then see the error for each ImportOperation by querying them by the respective state.