Import Containers

Import Containers serve as data containers for Import Resources.

Import Containers created without a retentionPolicy are automatically deleted 72 hours after creation. Set a TimeToLiveRetentionPolicy to use a custom duration (within the allowed minimum and maximum). See best practices for guidance on organizing containers.

Import Containers are the fundamental aspect of the Import API. To import resources into your Project, you create Import Requests in an ImportContainer. The system then processes the Import Resources within those Import Requests as ImportOperations.

You can view the current number of ImportOperations within an ImportContainer by getting the ImportSummary of the ImportContainer. ImportSummaries provide an aggregated summary of the status of all ImportOperations in an ImportContainer, including the number of successful and failed operations. For more ways of monitoring the status of your imports, see monitor the import process.

A maximum of 1 000 Import Containers can be created per Project. Merchant Center users may see a message that the maximum number of Import Containers has been reached. This is a soft limit that can be increased per Project after a performance impact review. See Limit increase guidance. For more information on using Import Containers effectively for your requirements, see best practices.

Get ImportContainer

GET

https://import.{region}.commercetools.com/{projectKey}/import-containers/{importContainerKey}

Retrieves an ImportContainer with the provided importContainerKey.

OAuth 2.0 Scopes:

manage_import_containers:{projectKey}view_import_containers:{projectKey}

Path parameters:

`region` String	The Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`importContainerKey` String	`key` of the ImportContainer.

Response:

200

ImportContainer

application/json

Request Example:cURL
curl --get https://import.{region}.commercetools.com/{projectKey}/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

200 Response Example: ImportContainerjson
{
  "key": "my-import-container",
  "version": 1,
  "createdAt": "2018-02-05T09:47:16.648Z",
  "lastModifiedAt": "2018-02-05T09:47:16.649Z",
  "expiresAt": "2018-02-08T09:47:16.648Z"
}

Get ImportSummary of ImportContainer

GET

https://import.{region}.commercetools.com/{projectKey}/import-containers/{importContainerKey}/import-summaries

Retrieves an ImportSummary for the ImportContainer with the provided importContainerKey. The returned values are eventually consistent.

OAuth 2.0 Scopes:

manage_import_containers:{projectKey}view_import_containers:{projectKey}

Path parameters:

`region` String	The Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`importContainerKey` String	`key` of the ImportContainer.

Response:

200

ImportSummary

application/json

Request Example:cURL
curl --get https://import.{region}.commercetools.com/{projectKey}/import-containers/{importContainerKey}/import-summaries -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: ImportSummaryjson
{
  "states": {
    "processing": 3,
    "validationFailed": 0,
    "unresolved": 0,
    "waitForMasterVariant": 0,
    "imported": 2,
    "rejected": 0,
    "canceled": 0,
    "partiallyImported": 0
  },
  "total": 5
}

Query ImportContainers

GET

https://import.{region}.commercetools.com/{projectKey}/import-containers

Retrieves all ImportContainers in the Project.

OAuth 2.0 Scopes:

manage_import_containers:{projectKey}view_import_containers:{projectKey}

Path parameters:

`region` String	The Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

`sort` String	See Sorting. The parameter can be passed multiple times.
`limit` Int64	Number of results requested. Default: `20` Minimum: `0` Maximum: `500`
`offset` Int64	Number of elements skipped. Default: `0` Maximum: `10000`

Response:

200

ImportContainerPagedResponse

application/json

Request Example:cURL
curl --get https://import.{region}.commercetools.com/{projectKey}/import-containers -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: ImportContainerPagedResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "key": "my-import-container",
      "version": 1,
      "createdAt": "2018-02-05T09:47:16.648Z",
      "lastModifiedAt": "2018-02-05T09:47:16.649Z"
    }
  ]
}

Create ImportContainer

POST

https://import.{region}.commercetools.com/{projectKey}/import-containers

Creates an Import Container in the Project.

Generates the ImportContainerCreated Event.

OAuth 2.0 Scopes:

manage_import_containers:{projectKey}

Path parameters:

`region` String	The Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Request Body:ImportContainerDraftasapplication/json

Response:

201

ImportContainer

application/json

Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/import-containers -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "key" : "my-import-container"
}
DATA

201 Response Example: ImportContainerjson
{
  "key": "my-import-container",
  "version": 1,
  "createdAt": "2018-02-05T09:47:16.648Z",
  "lastModifiedAt": "2018-02-05T09:47:16.649Z",
  "expiresAt": "2018-02-08T09:47:16.648Z"
}

Update ImportContainer

PUT

https://import.{region}.commercetools.com/{projectKey}/import-containers/{importContainerKey}

Updates an ImportContainer in the Project.

OAuth 2.0 Scopes:

manage_import_containers:{projectKey}

Path parameters:

`region` String	The Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`importContainerKey` String	`key` of the ImportContainer.

Request Body:ImportContainerUpdateDraftasapplication/json

Response:

200

ImportContainer

application/json

Request Example:cURL
curl -X PUT https://import.{region}.commercetools.com/{projectKey}/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "resourceType" : "product"
}
DATA

200 Response Example: ImportContainerjson
{
  "version": 2,
  "resourceType": "product",
  "key": "my-import-container",
  "createdAt": "2018-02-05T09:47:16.648Z",
  "lastModifiedAt": "2025-01-05T12:22:20.649Z"
}

Delete ImportContainer

DELETE

https://import.{region}.commercetools.com/{projectKey}/import-containers/{importContainerKey}

Deletes an Import Container in the Project.

Generates the ImportContainerDeleted Event.

OAuth 2.0 Scopes:

manage_import_containers:{projectKey}

Path parameters:

`region` String	The Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`importContainerKey` String	`key` of the ImportContainer.

Response:

200

ImportContainer

application/json

Request Example:cURL
curl -X DELETE https://import.{region}.commercetools.com/{projectKey}/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: ImportContainerjson
{
  "key": "my-import-container",
  "version": 1,
  "createdAt": "2018-02-05T09:47:16.648Z",
  "lastModifiedAt": "2018-02-05T09:47:16.649Z",
  "expiresAt": "2018-02-08T09:47:16.648Z"
}

Representations

ImportContainer -ImportContainerDraft -ImportContainerPagedResponse -ImportContainerUpdateDraft -ImportResourceType

ImportSummary -OperationStates

RetentionPolicy -TimeToLiveRetentionPolicy -TimeToLiveConfig

ImportContainer

Contains the resources to be imported. Unless resourceType is specified, the ImportContainer can import all of the supported ImportResourceTypes.

If the container was created without a retentionPolicy, it expires 72 hours after createdAt. If a TimeToLiveRetentionPolicy was set, expiry follows the configured timeToLive (between the minimum and maximum allowed values). The expiresAt field holds the calculated deletion time.

`version` Int64	Current version of the ImportContainer.
`key` String	User-defined unique identifier of the ImportContainer.
`resourceType` ImportResourceType	The resource type the ImportContainer supports. If not present, the ImportContainer can import all of the supported ImportResourceTypes.
`retentionPolicy` RetentionPolicy	Retention policy for this ImportContainer. If not set, the ImportContainer will expire 72 hours after creation.
`expiresAt` DateTime	Date and time (UTC) when the ImportContainer is automatically deleted. If no `retentionPolicy` was set at creation, this is 72 hours after `createdAt`. If a `TimeToLiveRetentionPolicy` was set, it is derived from `timeToLive`.
`createdAt` DateTime	Date and time (UTC) the ImportContainer was initially created.
`lastModifiedAt` DateTime	Date and time (UTC) the ImportContainer was last updated.

Example: json
{
  "key": "my-import-container",
  "version": 1,
  "createdAt": "2018-02-05T09:47:16.648Z",
  "lastModifiedAt": "2018-02-05T09:47:16.649Z",
  "expiresAt": "2018-02-08T09:47:16.648Z"
}

ImportContainerDraft

The representation sent to the server to create an ImportContainer.

If you omit retentionPolicy, the new ImportContainer uses the default 72-hour time to live. Set a TimeToLiveRetentionPolicy to use a custom duration (within the allowed minimum and maximum).

`key` String	User-defined unique identifier of the ImportContainer. Pattern: `^[a-zA-Z0-9_-]+$`
`resourceType` ImportResourceType	The resource type the ImportContainer will accept. If not specified, the ImportContainer can import all of the supported ImportResourceTypes.
`retentionPolicy` RetentionPolicy	Optional. When set, defines how long the ImportContainer is kept before automatic deletion. When omitted, the ImportContainer receives the default 72-hour lifetime.

Example: json
{
  "key": "my-import-container"
}

ImportContainerPagedResponse

PagedQueryResult with results containing an array of ImportContainer.

`limit` Int	Number of results requested. Default: `20`Minimum: `0`Maximum: `500`
`offset` Int64	Number of elements skipped. Default: `0`Maximum: `10000`
`count` Int64	Actual number of results returned.
`total` Int64	Total number of results matching the query.
`results` Array of ImportContainer	ImportContainers matching the query.

Example: json
{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "key": "my-import-container",
      "version": 1,
      "createdAt": "2018-02-05T09:47:16.648Z",
      "lastModifiedAt": "2018-02-05T09:47:16.649Z"
    }
  ]
}

ImportContainerUpdateDraft

The representation sent to the server when updating an ImportContainer.

`version` Int64	Current version of the ImportContainer.
`resourceType` ImportResourceType	The resource type to be imported. If not given, the ImportContainer is able to import all of the supported ImportResourceTypes.

Example: json
{
  "version": 1,
  "resourceType": "product"
}

ImportResourceType

The resource type that can be imported.

business-unit: The Business Unit import resource type.
category: The Category import resource type.
customer: The Customer import resource type.
discount-code: The Discount Code import resource type.
inventory: The Inventory import resource type.
order: The Order import resource type.
order-patch: The Order patch import resource type.
price: The Embedded Price import resource type.
product: The Product import resource type.
product-draft: The Product draft import resource type.
product-selection: The Product Selection import resource type.
product-tailoring: The Product Tailoring import resource type.
product-type: The Product Type import resource type.
product-variant: The Product Variant import resource type.
product-variant-patch: The Product Variant patch resource type.
standalone-price: The Standalone Price import resource type.
variant: The Variant import resource type.
type: The Type import resource type.

ImportSummary

The current status of ImportOperations in an ImportContainer.

`states` OperationStates	The current ProcessingStates of ImportOperations in an ImportContainer.
`total` Int64	The total number of ImportOperations in `states`.

Example: json
{
  "states": {
    "processing": 3,
    "validationFailed": 0,
    "unresolved": 0,
    "waitForMasterVariant": 0,
    "imported": 2,
    "rejected": 0,
    "canceled": 0,
    "partiallyImported": 0
  },
  "total": 5
}

OperationStates

The number of ImportOperations in each ProcessingState.

`processing` Int64	The number of ImportOperations in the `processing` state.
`validationFailed` Int64	The number of ImportOperations in the `validationFailed` state.
`unresolved` Int64	The number of ImportOperations in the `unresolved` state.
`waitForMasterVariant` Int64	The number of ImportOperations in the `waitForMasterVariant` state.
`imported` Int64	The number of ImportOperations in the `imported` state.
`rejected` Int64	The number of ImportOperations in the `rejected` state.
`canceled` Int64	The number of ImportOperations in the `canceled` state.
`partiallyImported` Int64	The number of ImportOperations in the `partiallyImported` state.

Example: json
{
  "processing": 3,
  "validationFailed": 0,
  "unresolved": 0,
  "waitForMasterVariant": 0,
  "imported": 2,
  "rejected": 0,
  "canceled": 0,
  "partiallyImported": 0
}

RetentionPolicy

Abstract parent type for retention policies, distinguished by the strategy field.

TimeToLiveRetentionPolicy

Set a time to live retention policy for the ImportContainer.

`strategy` StrategyEnum	`ttl` The strategy of the retention policy. Used to determine how the ImportContainer should be retained.
`config` TimeToLiveConfig	The configuration of the time to live retention policy.

TimeToLiveConfig

timeToLive

String

The time to live of the ImportContainer. Used to generate the expiresAt value of the ImportContainer. The lowest accepted value is 1h and the highest accepted value is 30d.

Pattern: ^(?:(d+)d|(d+)h|(d+)m)$

Import Containers

Get ImportContainer.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get ImportSummary of ImportContainer.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Query ImportContainers.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create ImportContainer.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Update ImportContainer.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Delete ImportContainer.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Representations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ImportContainer.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ImportContainerDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ImportContainerPagedResponse.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ImportContainerUpdateDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ImportResourceType.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ImportSummary.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

OperationStates.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

RetentionPolicy.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

TimeToLiveRetentionPolicy.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

TimeToLiveConfig.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get ImportContainer

Get ImportSummary of ImportContainer

Query ImportContainers

Create ImportContainer

Update ImportContainer

Delete ImportContainer

Representations

ImportContainer

ImportContainerDraft

ImportContainerPagedResponse

ImportContainerUpdateDraft

ImportResourceType

ImportSummary

OperationStates

RetentionPolicy

TimeToLiveRetentionPolicy

TimeToLiveConfig