To best utilize the Import API, we recommend the following best practices.
Effective use of Import Containers
Organize Import Containers
1 000 Import Containers and new Import Containers expire by default after 72 hours unless you set a retention policy.retentionPolicy.- When importing full data sets, a dedicated Import Container for that run can separate one import from another, provided the work finishes within the default
72-hour window or you set an appropriateretentionPolicy. - When performing routine imports, reuse a stable Import Container (for example, per resource type or integration) instead of minting a new key for every run.
- When importing from multiple sources, one Import Container per source can clarify monitoring and errors.
- When performing high-volume, short-lived imports, rely on the default
72-hour lifetime or tunetimeToLivevia TimeToLiveRetentionPolicy.
| Use Case | Possible Import Container organization |
|---|---|
| Import Product and Category | Create separate Import Containers for Product and Category |
| Import Price changes daily at 5 PM | Create a reusable Import Container. If there are more than 200 000 imports per day, this may be broken down by some other business logic or temporary Import Container for excess counts. |
| Import Product changes from multiple sources | Create one Import Container per source for Product imports. |
Optimize performance
200 000 Import Operations per Import Container. This way, monitoring activities at the container level will not be costly.48 hours after they are created, you can reuse Import Containers over time. An example schedule is as follows:| Day | Import Operation total count | Import Containers (Import Operation count) |
|---|---|---|
| Day 1 | 100,000 | container-a (100,000) |
| Day 2 | 500,000 | container-a (100,000), container-b (200,000), container-c (200,000) |
| Day 3 | 400,000 | container-a (0), container-b (200,000), container-c (200,000) |
| Day 4 | 200,000 | container-a (200,000), container-b (0), container-c (0) |
48 hours. container-a is now ready to be reused. Similarly container-b and container-c can be reused from Day 4.Clean up data from Import Containers and remove unused Import Containers
48 hours after they are created. That does not remove the Import Container itself.retentionPolicy, the default lifetime is 72 hours; if you set a TimeToLiveRetentionPolicy, the lifetime is defined by its timeToLive value (between 1 hour and 30 days).retentionPolicy, the Import Container is deleted 72 hours after creation. The Import Operations associated with this Import Container are also removed at this time.timeToLive so imports and monitoring finish before expiresAt. If you need a container to live longer than 30 days, you must create a new container or adjust your workflow. Newly created containers without a suitable policy do not have an unlimited default lifetime.Automatic deletion and retention policy
expiresAt for containers that follow the default or TTL-based lifecycle. Omitting retentionPolicy means the default 72-hour TTL. Setting a TimeToLiveRetentionPolicy sets expiresAt from your timeToLive value. When expiresAt is reached, the ImportContainer and its Import Operations are permanently deleted.Import large data sets
20 resources per Import Request. If you have a huge number of resources to import, we recommend using thread optimization to send your data as fast as possible to an Import Container.Rate limits
The Import API does not have rate limits, but to ensure the best performance we recommend that you send 300 API calls per second, per Project, to the Import API.
20 CategoryImport items, this means that up to 360,000 Categories can be sent to the Import API every minute.Update existing resources safely
Treat every import request for an existing resource as the complete definition of that resource, and use the following practices to avoid unintended data loss:
- Send all existing values you want to keep. If your source system does not hold every value, such as images managed in a separate system, read the resource through the HTTP API, merge your changes into it, and import the merged result.
- Use the narrowest import resource. To change only Attribute values of a Product Variant, use Product Variant Patches. To change Prices within a Product Variant, use Embedded Prices, which leave the other Prices of the Product Variant unchanged. To change Product data without touching Product Variants and Prices, use Products.
- Avoid partial payloads from multiple sources. When several systems write the same resource, each import must still contain the complete resource. Alternatively, assign each system to a different import resource, such as one system for Product Variants and another for Embedded Prices.
- Test updates in a staging Project. Import a sample update and compare the resource before and after the import.
- Apply staged changes of StandalonePrices first. StandalonePriceImport has no
stagedfield, so every update through the Import API discards the pending staged changes of an existing StandalonePrice, even if the importedvalueis the same. To keep them, first apply them with the Apply Staged Changes update action.
Example: update the images of a Product Variant
The following Product Variant exists in the Project. It has Attributes, images, and Assets.
{
"key": "red-t-shirt-m",
"sku": "red-t-shirt-m",
"attributes": [
{ "name": "color", "value": "red" },
{ "name": "size", "value": "M" }
],
"images": [
{
"url": "https://example.com/images/red-t-shirt-front.jpg",
"dimensions": { "w": 1400, "h": 1400 }
}
],
"assets": [
{
"key": "red-t-shirt-size-guide",
"name": { "en": "Size guide" },
"sources": [{ "uri": "https://example.com/assets/red-t-shirt-size-guide.pdf" }]
}
]
}
An import request that only contains the new image removes the Attributes and Assets, because they are omitted:
{
"type": "product-variant",
"resources": [
{
"key": "red-t-shirt-m",
"sku": "red-t-shirt-m",
"product": { "typeId": "product", "key": "t-shirt" },
"isMasterVariant": false,
"images": [
{
"url": "https://example.com/images/red-t-shirt-back.jpg",
"dimensions": { "w": 1400, "h": 1400 }
}
]
}
]
}
Instead, include the existing values you want to keep together with the change. This request replaces the image and keeps the Attributes and Assets:
{
"type": "product-variant",
"resources": [
{
"key": "red-t-shirt-m",
"sku": "red-t-shirt-m",
"product": { "typeId": "product", "key": "t-shirt" },
"isMasterVariant": false,
"attributes": [
{ "name": "color", "type": "text", "value": "red" },
{ "name": "size", "type": "text", "value": "M" }
],
"images": [
{
"url": "https://example.com/images/red-t-shirt-back.jpg",
"dimensions": { "w": 1400, "h": 1400 }
}
],
"assets": [
{
"key": "red-t-shirt-size-guide",
"name": { "en": "Size guide" },
"sources": [{ "uri": "https://example.com/assets/red-t-shirt-size-guide.pdf" }]
}
]
}
]
}
Example: change a Price without changing the Product Variant
key, and the Attributes, images, Assets, and other Prices of the Product Variant are not changed. Include all existing values of the Price you want to keep, such as country, validFrom, and validUntil.{
"type": "price",
"resources": [
{
"key": "red-t-shirt-m-eur-de",
"productVariant": { "typeId": "product-variant", "key": "red-t-shirt-m" },
"product": { "typeId": "product", "key": "t-shirt" },
"country": "DE",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 2499
}
}
]
}
Choose the right Product import endpoint
The Import API has multiple endpoints for importing Product data. The following table summarizes what can be imported by each endpoint.
| Endpoint | What can be imported |
|---|---|
| Product Drafts | Product data including Product Variants and Prices. |
| Products | Product data without Product Variants and Prices. |
| Product Variants | Product Variant data without Prices. |
| Product Variant Patches | Product Variant Attribute data. |
| Embedded Prices | Price data for a specific Product Variant. |
The following information explains common use cases for each endpoint.
Product Drafts
Common use cases:
- when you want to update a Product with 10+ new Product Variants, each with 20+ Embedded Prices.
- when you want to update a large number of Product Variants with new Attribute values and Prices.
Products
attributes you want to keep, as omitted Attributes are removed.Product Variants
sku, attributes, images, and assets of the Product Variant, as omitted values are removed. The import does not change the Embedded Prices of an existing Product Variant. A new Product Variant has no Embedded Prices, so import them separately with Embedded Prices.Product Variant Patches
Embedded Prices
Manage published state of Products
publish which accepts a boolean value. The result of using this field varies based on whether you are importing data to create or update Products.When importing data to create a Product
true, the Product is created and published immediately. If false, the Product is created but not published.When importing data to update an existing Product
The result of updating existing Products depends on if you are including changes in your import request, and if the Product currently has staged changes.
Value of publish | Does the import request have changes? | Does the Product have staged changes before importing? | Result |
|---|---|---|---|
true | No | Yes | The staged changes are applied to the current projection and the Product is published. |
true | No | No | If the Product is currently unpublished, it is published to the current projection. |
true | Yes | N/A | The changes are applied to both the current and staged projection.
|
false | No | N/A | The Product is unpublished. |
false | Yes | N/A | The changes are applied to the staged projection, the Product is unpublished, and hasStagedChanges becomes true. |
Utilize the lifetime of Import Operations
48 hours to allow you to send other resources, including those referenced by other resources (unresolved references), during this time period.48 hours and waits for the Product to be imported.Handle retries
rejected status. In other cases, the Import API will handle the retry internally without you needing to do anything.What not to do
Do not send duplicate import requests concurrently. Since the Import API imports data asynchronously, the order is not guaranteed. It may also lead to a concurrent modification error.
errors field.Avoid concurrency errors
product field in the ProductVariantPatch minimizes concurrency errors during the import process.product field on one ProductVariantPatch, you have to set it for every ProductVariantPatch in the same ProductVariantPatchRequest.
Otherwise, the API returns an InvalidField error.