# Import API overview

Overview of the concepts related to the Import API.

The Import API is largely in [public beta](/offering/compatibility.md#public-beta). Some foundational parts of the API have reached general availability, while the resource-specific import endpoints remain in public beta:

- **Generally available:** [Import Containers](/api/import-export/import-container.md), [Import Operations](/api/import-export/import-operation.md) (including [Processing States](/api/import-export/import-operation.md#processingstate)), and [Import Summaries](/api/import-export/import-container.md#importsummary).
- **Public beta:** all [Import Requests](/api/import-export/import-requests.md) (for example, for Products, Prices, and Categories) and the [Import Resources](/api/import-export/import-resources.md) they contain.

Functionality that is in public beta is marked with a  tag.

The Import API allows you to bulk-upload large volumes of commerce data into your Project. It is optimized for high-performance data ingestion and minimizes the manual overhead of managing complex data relationships.

Unlike the HTTP API, which is designed for real-time transactional updates, the Import API uses an asynchronous workflow to process data in JSON format.

If you want to import data from CSV files, you can use the [CSV Import feature](/merchant-center/import-data.md) in the Merchant Center.

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 commercetools 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 functionality | Import API | Other APIs |
| --- | --- | --- |
| Type of API | Asynchronous and eventually consistent. | Synchronous and transactional. |
| Create resources | Create **20** resources per API call. | Create one resource per API call. |
| Update resources | If 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 resources | You cannot delete resources with the Import API. | Most resource types have endpoints for deleting individual resources. |
| Dependency handling | The Import API automatically [identifies and resolves dependencies](/api/import-export/overview.md#reference-resolution), such as references between imported resources. | You must consider all dependencies before creating/updating resources. |
| Order of API calls | The 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

commercetools commerce APIs typically use defined endpoints for creating or updating resources. In contrast, the Import API utilizes [ImportContainers](/api/import-export/overview.md#what-are-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](/api/import-export/overview.md#what-are-importcontainers).
2. **POST** an [ImportRequest](/api/import-export/overview.md#what-are-importrequests) to the ImportContainer, which then returns an [ImportResponse](/api/import-export/overview.md#what-are-importresponses).
   - The resources in the ImportRequest are asynchronously imported, with their import status represented as [ImportOperations](/api/import-export/overview.md#what-are-importoperations).
3. [Monitor the import process](/api/import-export/overview.md#monitor-the-import-process) and respond to any errors.
4. Reuse the ImportContainer for future imports **within its lifetime**:
   - New containers created **without** a `retentionPolicy` **expire 72 hours** after creation.
   - Reuse the same key only while the ImportContainer exists.
   - Set a [retention policy](/api/import-export/import-container.md#retentionpolicy) if you need a longer lifetime.
   - Create another ImportContainer when needed.

### What are ImportContainers?

[ImportContainers](/api/import-export/import-container.md#importcontainer) represent where the resources within [ImportRequests](/api/import-export/overview.md#what-are-importrequests) are contained before being imported.

You **POST** ImportRequests to an ImportContainer, and the Import API creates one [ImportOperation](/api/import-export/overview.md#what-are-importoperations) per resource in the ImportRequest. The resources are then asynchronously imported into your Project. To achieve the [best performance](/api/import-export/best-practices.md#effective-use-of-import-containers), we recommend having fewer than **200000** 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). **By default**, a new Import Container is **removed automatically 72 hours** after creation. You can set a [TimeToLiveRetentionPolicy](/api/import-export/import-container.md#timetoliveretentionpolicy) on create if you need a different duration (within the allowed minimum and maximum). See [best practices](/api/import-export/best-practices.md#effective-use-of-import-containers) for planning container usage.

Up to **1000** Import Containers can be created per Project.

### What are ImportRequests?

The Import API uses resource-specific [ImportRequests](/api/import-export/import-requests.md) to create/update resources. This is different from other commercetools commerce APIs, which use drafts and update actions to perform these 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?

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 commercetools commerce API.
- To set `orderNumber` on an Order, use [Set Order Number](/api/projects/orders.md#set-order-number).

For most resources, 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`), the Import API updates it.
- If no matching resource exists, a new resource is created with the given `key`.

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

##### Orders and ProductVariants

Orders and ProductVariants have specific ImportRequests that determine whether to create or update them.

- For Orders:
  - Use [OrderImportRequest](/api/import-export/import-requests.md#orderimportrequest) to create new Orders.
  - Use [OrderPatchImportRequest](/api/import-export/import-requests.md#orderpatchimportrequest) to update existing Orders.
- For ProductVariants:
  - Use [ProductVariantImportRequest](/api/import-export/import-requests.md#productvariantimportrequest) to create new ProductVariants.
  - Use [ProductVariantPatchRequest](/api/import-export/import-requests.md#productvariantpatchrequest) to update existing ProductVariants.

#### Supported resources

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

- **BusinessUnits**
  - [BusinessUnitImportRequest](/api/import-export/import-requests.md#businessunitimportrequest) 
- **Categories**
  - [CategoryImportRequest](/api/import-export/import-requests.md#categoryimportrequest) 
- **Customers**
  - [CustomerImportRequest](/api/import-export/import-requests.md#customerimportrequest) 
- **DiscountCodes**
  - [DiscountCodeImportRequest](/api/import-export/import-requests.md#discountcodeimportrequest) 
- **InventoryEntry**
  - [InventoryImportRequest](/api/import-export/import-requests.md#inventoryimportrequest) 
- **Orders**
  - [OrderImportRequest](/api/import-export/import-requests.md#orderimportrequest) 
  - [OrderPatchImportRequest](/api/import-export/import-requests.md#orderpatchimportrequest) 
- **Products**
  - [ProductDraftImportRequest](/api/import-export/import-requests.md#productdraftimportrequest) 
  - [ProductImportRequest](/api/import-export/import-requests.md#productimportrequest) 
  - [ProductVariantImportRequest](/api/import-export/import-requests.md#productvariantimportrequest) 
  - [ProductVariantPatchRequest](/api/import-export/import-requests.md#productvariantpatchrequest) 
  - [VariantImportRequest](/api/import-export/import-requests.md#variantimportrequest) 
  - [EmbeddedPriceImportRequest](/api/import-export/import-requests.md#embeddedpriceimportrequest) 
- **ProductSelections**
  - [ProductSelectionImportRequest](/api/import-export/import-requests.md#productselectionimportrequest) 
- **ProductTailoring**
  - [ProductTailoringImportRequest](/api/import-export/import-requests.md#producttailoringimportrequest) 
- **ProductTypes**
  - [ProductTypeImportRequest](/api/import-export/import-requests.md#producttypeimportrequest) 
- **StandalonePrices**
  - [StandalonePriceImportRequest](/api/import-export/import-requests.md#standalonepriceimportrequest) 
- **Types**
  - [TypeImportRequest](/api/import-export/type.md#typeimportrequest) 

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](/api/import-export/best-practices.md#choose-the-right-product-import-endpoint).

### What are ImportResponses?

You receive an [ImportResponse](/api/import-export/import-requests.md#importresponse) after posting an ImportRequest to an ImportContainer.

Receiving an ImportResponse does not mean that the resources have been imported. An ImportResponse indicates that the resources within the ImportRequest as [ImportOperations](/api/import-export/overview.md#what-are-importoperations) are now being processed. This is different from other commercetools APIs, where a successful response to a **POST** call indicates a resource has been created/updated.

### What are ImportOperations?

[ImportOperations](/api/import-export/import-operation.md#importoperation) represent the status of a resource being imported. The Import API creates an ImportOperation for each resource within an [ImportRequest](/api/import-export/overview.md#what-are-importrequests).

An ImportOperation includes its current [state](/api/import-export/import-operation.md#processingstate), and may also include [errors](/api/errors.md#import-api-specific-errors) and [unresolved references](/api/import-export/overview.md#reference-resolution).

When an ImportOperation has the `imported` state, the resource has been created/updated. Other [states](/api/import-export/import-operation.md#processingstate) 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. This allows you to track the progress of imports and troubleshoot any issues that may arise.

| Endpoints | Use case |
| --- | --- |
| [Get ImportSummary of ImportContainer](/api/import-export/import-container.md#get-importsummary-of-importcontainer) | Retrieve an aggregated summary of the status of all ImportOperations in an ImportContainer. |
| [Query ImportOperations in ImportContainer](/api/import-export/import-operation.md#query-importoperations-in-importcontainer) | Monitor the status of all ImportOperations within an ImportContainer. You can filter query results or use `debug` mode to fetch unresolved references. |
| [Get ImportOperation](/api/import-export/import-operation.md#get-importoperation) | View the status of a specific ImportOperation. |

You can also [subscribe](/api/projects/subscriptions.md) to [Import API Events](/api/events.md#import-api-events)  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](/merchant-center/import-data.md#import-logs), which provide detailed information about import progress and status, 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 Project.

The `unresolvedReferences` field of an [ImportOperation](/api/import-export/import-operation.md#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.

The Import API does not duplicate the validation logic of other commercetools commerce APIs. This means that a successful reference resolution does not guarantee data consistency in your Project. For example, the uniqueness of a Product Variant's `sku` cannot be checked by the Import API but only by other commercetools commerce APIs.

## Other ways to import data

The [Java SDK](/api/dev-tooling/jvm-sdk.md), [TypeScript SDK](/api/dev-tooling/typescript-sdk.md), [PHP SDK](/api/dev-tooling/php-sdk.md), and [.NET SDK](/api/dev-tooling/dotnet-sdk.md) provide full support for the Import API.

You can also [import data from CSV files](/merchant-center/import-data.md) in the Merchant Center.

To synchronize data between Projects, you can use the Dockerized [commercetools-project-sync](https://github.com/commercetools/commercetools-project-sync) CLI application.

[commercetools-project-sync](https://github.com/commercetools/commercetools-project-sync) operates independently of the Import API. 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](/learning-composable-commerce-developer-essentials/import-api/overview.md).

## Related pages

- [Area overview page with navigation](/api.md)
- [Next page: Best practices](/api/import-export/best-practices.md)