Import API overview

The Import API allows you to upload large amount of data to commercetools Composable Commerce.

Use the Import API to design applications that upload large amounts of resources into your Composable Commerce Project. Resources of the supported ImportResourceTypes can be imported with the Import API.

The Import API performs asynchronous data import and automatically handles dependencies between resources. The arrows in the following diagram indicate the data flow.

Our Java, TypeScript, PHP, and .NET SDKs provide full support for the Import API.

Learn how to use the Import API using the Java or TypeScript SDKs in our self-paced Import API module.

You can import data from CSV files directly from the Merchant Center.

To synchronize data between Composable Commerce Projects, you can use the Dockerized commercetools-project-sync CLI application. Note that this application is independent of the Import API and has its own set of supported resources.

Advantages of the Import API

The Import API provides 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 specific resources, including 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 with CLI and UI tools, the Import API provides better opportunities for integration with modern application infrastructure.

Comparing the Import API with other HTTP APIs

You can create and update resources in your Composable Commerce Project using the Import API or other HTTP APIs. The following table explains the main differences between the APIs.

Functionality	Import API	HTTP APIs
Upload method	Asynchronous	Synchronous
Updating resources	Including the `key` of an existing resource in your import request will update the resource with the specified values.	Different resource types have their own update actions. You must check what update actions to use and include them in an API call to a specific resource.
Dependency handling	The Import API identifies and resolves dependencies between imported resources.	All dependencies must be considered beforehand. Dependent resources must be uploaded in the right order.
Order of API calls	The order of API calls does not matter. The Import API waits for missing dependencies. Resources may not be imported in the order they were uploaded.	The order of API calls matters and operations arrive in the order they were imported.
Status monitoring	You can actively query the status of the import process.	As this process happens synchronously, responses indicate either success or failure. You cannot query the status of the process.

How to use the Import API

Use keys as identifiers

The key field is an optional user-defined identifier when using other HTTP APIs, but is required when using the Import API. This is due to the id field not being present on resources until they are created.

If a resource with the specified key exists when importing data, the Import API updates that resource with the imported data. If a resource with the specified key does not exist, the Import API creates a new resource.

ImportRequest

An ImportRequest is the data type that is sent in a request body to create or update resources in a 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.

Import API Workflow

The Import API employs the following workflow.

Create an ImportContainer.
Next, create an ImportRequest and post it to a resource-specific endpoint for import (for example, Import Categories). This initiates an import process.
After sending the ImportRequest, the Import API returns an ImportResponse, the list of newly created ImportOperations and their validation statuses.
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.
The Import API validates the import data structures and updates state of ImportOperations. For more information, see Processing State.
If the import is successful, state of the ImportOperations becomes "imported". The corresponding resource is now imported into the Project.
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.

How to monitor the import status

Use Get ImportOperation to see the status of each import resource, Query ImportOperations to get the status of all import resources in a specific ImportContainer, or Get ImportSummary to see the number of import resources in each Processing State.