Documentation

Import API overview

Overview of the concepts related to the Import API.

The Import API is designed for high speed, large volume, and automatic handling of resource dependencies. By using the Import API, you can:

  • Create/update up to 20 resources in a single API call.
  • Use user-defined identifiers, like key, to ensure synchronization of resources across multiple Projects.
  • Split large Product updates into specific imports for metadata, Product Variants, and Prices.
  • Automatically resolve dependencies, such as parental relationships of Categories.
  • Integrate with external systems and applications easier than using CLI and UI tools.

Why choose the Import API?

The Import API operates independently from other Composable Commerce APIs. Both can be used to create and update resources in your Project.

The following table highlights the main differences between the Import API and other APIs, helping you choose the right API for your needs.

API functionalityImport APIOther APIs
Type of APIAsynchronous and eventually consistent.Synchronous and transactional.
Create resourcesCreate 20 resources per API call.Create one resource per API call.
Update resourcesIf you import a resource which exists in your Project with the specified key/orderNumber, the Import API updates that resource.Each resource type uses distinct update actions. To update a resource, you must first identify the correct actions, then arrange them in a specific order within an array, and finally include this array in your API request.
Delete resourcesYou cannot delete resources with the Import API.Most resource types have endpoints for deleting individual resources.
Dependency handlingThe Import API automatically identifies and resolves dependencies, such as references between imported resources.You must consider all dependencies before creating/updating resources.
Order of API callsThe order of API calls does not matter because resources are processed asynchronously, and dependencies are resolved automatically. Resources may be imported in a different order than they were uploaded.You must send API calls in the correct order, as operations arrive in the same sequence.

How to use the Import API

Composable Commerce APIs typically use defined endpoints for creating or updating resources. In contrast, the Import API utilizes ImportContainers. You send import data to ImportContainers using a POST request. The Import API then automatically processes the data within the ImportContainer.

The following steps summarize how to use the Import API:

  1. Create an ImportContainer.
  2. POST an ImportRequest to the ImportContainer, which then returns an ImportResponse.
    • The resources in the ImportRequest are asynchronously imported, with their import status represented as ImportOperations.
  3. Monitor the import process and respond to any errors.
  4. Reuse the ImportContainer for future imports.

What are ImportContainers?

ImportContainers represent where the resources within ImportRequests are contained before being imported.
You POST ImportRequests to an ImportContainer, and the Import API creates one ImportOperation per resource in the ImportRequest. The resources are then asynchronously imported into your Project. To achieve the best performance, we recommend having fewer than 200 000 ImportOperations per ImportContainer.
For greater organization, you can create resource-specific Import Containers (for example, one for importing Categories, and another for importing Standalone Prices). If you do not intend to reuse an ImportContainer, you can configure it to be automatically deleted after a specified time to live value.
Up to 1 000 Import Containers can be created per Project.

What are ImportRequests?

Unlike other Composable Commerce APIs which use drafts and update actions to create/update resources, the Import API uses resource-specific ImportRequests to perform both tasks.
ImportRequests can contain up to 20 resources to import. Resources are identified by the key identifier, except for Orders, which use orderNumber. Both key and orderNumber are user-defined identifiers, making them more flexible and predictable than system-generated and Project-specific id identifiers. By using key and orderNumber, you ensure consistent synchronization of resources across multiple Projects, such as staging and production environments, without being tied to unique id values that vary between Projects.

How are resources created or updated?

The Import API performs "upsert" operations, meaning it either updates an existing resource or creates a new one.

  • If a resource in the ImportRequest already exists in your Project (identified by its key or orderNumber), the Import API updates it.
  • If no matching resource exists, a new resource is created with the given key or orderNumber.
For example, if you import a Product with the key "product-123" and it already exists in your Project, the Import API updates that Product. If no Product with the key "product-123" exists, a new Product is created with that key.
You cannot use the Import API to set or update the key/orderNumber of an existing resource.
  • To set or update key values on existing resources, use the "Set Key" update action in the appropriate resource-specific Composable Commerce API.
  • To set orderNumber on an Order, use Set Order Number.

Supported resources

The Import API supports a subset of Composable Commerce resources. The following list contains supported resources and their respective ImportRequests.

To help reduce the amount of data to import, the Import API has multiple ways of importing different aspects of Product data. For more information, see Choose the right Product import endpoint.

What are ImportResponses?

You receive an ImportResponse after posting an ImportRequest to an ImportContainer.
Unlike other Composable Commerce APIs, where a successful response to a POST call indicates a resource has been created/updated, an ImportResponse does not mean that the resources have been imported. An ImportResponse indicates that the resources within the ImportRequest as ImportOperations are now being processed.

What are ImportOperations?

ImportOperations represent the status of a resource being imported. The Import API creates an ImportOperation for each resource within an ImportRequest.
An ImportOperation includes its current state, and may also include errors and unresolved references.
When an ImportOperation has the imported state, the resource has been created/updated. Other states may indicate a failure to import the resource, or that the resource is still being processed.
ImportOperations are deleted 48 hours after they are created.

Monitor the import process

The Import API provides the following endpoints to monitor the import process, allowing you to track the progress of imports and troubleshoot any issues that may arise.

EndpointsUse case
Get ImportSummary of ImportContainerRetrieve an aggregated summary of the status of all ImportOperations in an ImportContainer.
Query ImportOperations in ImportContainerMonitor the status of all ImportOperations within an ImportContainer. You can filter query results or use debug mode to fetch unresolved references.
Get ImportOperationView the status of a specific ImportOperation.
You can also subscribe to Import API Events BETA to receive automatic, real-time status updates. These events include notifications about ImportOperations being rejected, unresolved references, and other status changes, allowing you to monitor and respond to the import process efficiently.
Merchant Center users can monitor the import status using Import logs, which provide detailed information about the progress and status of imports, including errors and unresolved references. These logs complement the API monitoring endpoints by offering a user-friendly interface for tracking and troubleshooting import operations.

Reference resolution

References for a resource are considered "resolved" when the resources it references are present in your Composable Commerce Project.

The unresolvedReferences field of an ImportOperation contains a list of references that could not be resolved. If a referenced resource is created or imported within the 48 hour lifespan of the ImportOperation, any references to it will be resolved. The ImportOperation will then be retried up to 5 times.
Because the Import API does not duplicate the validation logic of other Composable Commerce APIs, a successful reference resolution does not guarantee data consistency in your Composable Commerce Project. For example, the uniqueness of a Product Variant's sku cannot be checked by the Import API but only by other Composable Commerce APIs.

Other ways to import data

The Java SDK, TypeScript SDK, PHP SDK, and .NET SDK provide full support for the Import API.
You can also import data from CSV files in the Merchant Center.
To synchronize data between Composable Commerce Projects, you can use the Dockerized commercetools-project-sync CLI application.
commercetools-project-sync operates independently of the Import API, meaning it uses a different mechanism and does not rely on the Import API for its functionality. It also has its own set of supported resources.

Further learning

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