Documentation

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.

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

Import API scheme
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.

Compare 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.

FunctionalityImport APIHTTP APIs
Upload methodAsynchronousSynchronous
Updating resourcesIncluding 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 handlingThe 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 callsThe 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 monitoringYou 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

Identifiers

The Import API uses only user-defined identifiers to identify resources. This is a key difference from other HTTP APIs, which can use the system-generated id.
id values are unique within a single Project. This makes them unsuitable for managing data across multiple Projects (such as staging and production). In these scenarios, resource id values will differ between Projects, whereas user-defined identifiers can be maintained consistently. Relying solely on user-defined identifiers therefore ensures predictable and reliable data imports across different Projects.
The Import API uses key to identify all resources, with the exception of OrderImport BETA and OrderPatchImport BETA which use orderNumber.

If a resource with the specified identifier exists when importing data, the Import API updates that resource with the imported data. If a resource with the specified identifier 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.

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

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.

Subscribe to Import API Events BETA

To receive automatic, real-time status updates, subscribe to Import API Events.