Import Operations

Represents the import status of an individual resource.

After you create an Import Request, the system creates one ImportOperation per resource in the Import Request.
ImportOperations contain information about the resource being imported, such as its ProcessingState and any UnresolvedReferences.
You can monitor the import process using Get ImportOperation to view the status of a single ImportOperation, or Query ImportOperations in ImportContainer to view all of the ImportOperations within a single ImportContainer.
ImportOperations are automatically deleted 48 hours after they are created.
To achieve the best performance with the Import API, we recommend to use fewer than 200 000 Import Operations per Import Container.

Representations

ImportOperation

Represents the import status of a resource.

id
String

Unique identifier of the ImportOperation.

version
Int

Current version of the ImportOperation.

importContainerKey
String
key of the ImportContainer.
resourceKey
String
key of the resource being imported.
state
The import status of the resource. If rejected or validationFailed, the import was unsuccessful.
resourceVersion
Int
The version of the imported resource when the import was successful.
errors
Array of ErrorObject
Contains errors if the import was unsuccessful. See Errors.
unresolvedReferences

If the resource being imported contains references to resources which do not exist, these references are contained within this array.

expiresAt
DateTime

Date and time (UTC) the ImportOperation will be deleted.

createdAt
DateTime

Date and time (UTC) the ImportOperation was created.

lastModifiedAt
DateTime

Date and time (UTC) the ImportOperation was last updated.

Example: json
{
  "version": 3,
  "state": "validationFailed",
  "errors": [
    {
      "code": "RequiredField",
      "message": "The required field 'key' is missing.",
      "field": "key"
    }
  ],
  "importContainerKey": "category-import-container",
  "id": "252c6ed3-c668-4610-afe9-87b9255e62e0",
  "resourceKey": "root-category",
  "resourceType": "category",
  "createdAt": "2018-02-05T09:47:16.648Z",
  "lastModifiedAt": "2018-02-05T09:47:16.649Z",
  "expiresAt": "2018-02-08T09:47:16.649Z"
}

ImportOperationPagedResponse

PagedQueryResult for Import Operations.
limit
Int
Default20Minimum0Maximum500
offset
Int
Number of elements skipped.
Default0Maximum10000
count
Int

The actual number of results returned.

total
Int

The total number of import operations matching the query.

results
Array of ImportOperation

The array of Import Operations matching the query.

Example: json
{
  "limit": 100,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "version": 3,
      "state": "validationFailed",
      "errors": [
        {
          "code": "RequiredField",
          "message": "The required field 'key' is missing.",
          "field": "key"
        }
      ],
      "importContainerKey": "category-import-container",
      "resourceKey": "root-category",
      "resourceType": "category",
      "id": "252c6ed3-c668-4610-afe9-87b9255e62e0",
      "createdAt": "2018-02-05T09:47:16.648Z",
      "lastModifiedAt": "2018-02-05T09:47:16.649Z",
      "expiresAt": "2018-02-08T09:47:16.649Z"
    }
  ]
}

ImportOperationStatus

The status of a new ImportOperation.
operationId
String
id of the ImportOperation.
Validation state of the ImportOperation.
errors
Array of ErrorObject
Example: json
{
  "state": "processing",
  "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
}

ImportOperationState

Describes the validation state of a newly created ImportOperation.
processing

The import is in process. This is the initial state of the ImportOperation.

validationFailed

The validation of the import resource failed.

ProcessingState

Every Import Operation is assigned one of the following states.
processing

The initial state assigned if the request payload (JSON structure and fields) meets Import API specifications. The resource import is in progress.

validationFailed
Either the request payload is missing the data as per Import API specifications, or even though the references were resolved, the data does not meet validation constraints. Generates the ImportValidationFailed Event.
unresolved
The import request contains KeyReferences to resources that do not exist in your Composable Commerce Project. Generates the ImportUnresolved Event.
waitForMasterVariant
Products must have at least one Product Variant, also known as the Master Variant. If you import a Product without a Master Variant, the import request will have this status until another import request includes Master Variant data for the Product. Generates the ImportWaitForMasterVariant Event.
imported

The resource was successfully imported.

rejected
The resource could not be imported. References were resolved, but the system could not import the data due to an internal server error and the retry limit was reached. Generates the ImportOperationRejected Event.
canceled

The import request was canceled and the resource was not imported.

UnresolvedReferences

Contains a reference to a resource which does not exist. For example, if a Category is imported with a parent Category that does not exist, the reference to the parent Category is an unresolved reference.

key
String
key of the unresolved resource.
typeId

Type of the unresolved resource.

Example: json
{
  "key": "key-of-unresolved-category-being-referenced",
  "typeId": "category"
}

Get ImportOperation

GET
https://import.{region}.commercetools.com/{projectKey}/import-operations/{id}
Retrieves an ImportOperation with the provided id.
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.
id
String
id of the ImportOperation.
Response:
200

ImportOperation

asapplication/json
Request Example:cURL
curl --get https://import.{region}.commercetools.com/{projectKey}/import-operations/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ImportOperationjson
{
  "version": 3,
  "state": "validationFailed",
  "errors": [
    {
      "code": "RequiredField",
      "message": "The required field 'key' is missing.",
      "field": "key"
    }
  ],
  "importContainerKey": "category-import-container",
  "id": "252c6ed3-c668-4610-afe9-87b9255e62e0",
  "resourceKey": "root-category",
  "resourceType": "category",
  "createdAt": "2018-02-05T09:47:16.648Z",
  "lastModifiedAt": "2018-02-05T09:47:16.649Z",
  "expiresAt": "2018-02-08T09:47:16.649Z"
}

Query ImportOperations in ImportContainer

GET
https://import.{region}.commercetools.com/{projectKey}/import-containers/{importContainerKey}/import-operations
Retrieves all ImportOperations within an ImportContainer.
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.
Query parameters:
sort
String
See Sorting.
The parameter can be passed multiple times.
limit
Int
Default: 20
Minimum: 0
Maximum: 500
offset
Int
Number of elements skipped.
Default: 0
Maximum: 10000
resourceKey
String
key of the ImportOperation to retrieve.
state
state of the ImportOperations to retrieve.
debug
Boolean
In case of Unresolved, it will show the unresolved references.
Default: false
Response:
200

ImportOperationPagedResponse

asapplication/json
Request Example:cURL
curl --get https://import.{region}.commercetools.com/{projectKey}/import-containers/{importContainerKey}/import-operations -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ImportOperationPagedResponsejson
{
  "limit": 100,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "version": 3,
      "state": "validationFailed",
      "errors": [
        {
          "code": "RequiredField",
          "message": "The required field 'key' is missing.",
          "field": "key"
        }
      ],
      "importContainerKey": "category-import-container",
      "resourceKey": "root-category",
      "resourceType": "category",
      "id": "252c6ed3-c668-4610-afe9-87b9255e62e0",
      "createdAt": "2018-02-05T09:47:16.648Z",
      "lastModifiedAt": "2018-02-05T09:47:16.649Z",
      "expiresAt": "2018-02-08T09:47:16.649Z"
    }
  ]
}