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 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, 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
The following steps summarize how to use the Import API:
- Create an ImportContainer.
- 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.
- Monitor the import process and respond to any errors.
- Reuse the ImportContainer for future imports.
What are ImportContainers?
200 000
ImportOperations per ImportContainer.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.
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
ororderNumber
), the Import API updates it. - If no matching resource exists, a new resource is created with the given
key
ororderNumber
.
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
.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.
- Categories
- Customers
- DiscountCodes
- InventoryEntry
- Orders
- OrderImportRequest BETA
- OrderPatchImportRequest BETA
- Products
- ProductTypes
- StandalonePrices
- Types
- TypeImportRequest BETA
What are ImportResponses?
What are ImportOperations?
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.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.
Endpoints | Use case |
---|---|
Get ImportSummary | Retrieve an aggregated summary of the status of all ImportOperations in an ImportContainer. |
Query ImportOperations | Monitor the status of all ImportOperations within an ImportContainer. |
Get ImportOperation | View the status of a specific ImportOperation. |
Reference resolution
References for a resource are considered "resolved" when the resources it references are present in your Composable Commerce Project.
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.sku
cannot be checked by the Import API but only by other Composable Commerce APIs.