Import Requests

Import Requests represent how you send resources to the Import API.

To import resources into your Project, include them in the resources field of an ImportRequest, and create an Import Request. The system then creates one ImportOperation per resource in the ImportRequest, and returns the initial status of the import to you in an ImportResponse.
Import Requests are resource-specific and can contain up to 20 resources. After making the request, you can monitor the import process.
Multiple requests can be sent to the same ImportContainer at the same time, but to achieve the best performance with the Import API, we recommended having fewer than 200 000 ImportOperations per ImportContainer.

Representations

ImportRequest

CategoryImportRequest

The request body to import Categories. Contains data for Categories to be created or updated in a Project.
type​
category

The resource types that can be imported.

resources​
Array of CategoryImport​

The category import resources of this request.

MaxItems: 20​
Example: json
{
  "type": "category",
  "resources": [
    {
      "key": "category-to-import",
      "name": {
        "en": "Category to import"
      },
      "slug": {
        "en": "category-to-import-slug"
      },
      "description": {
        "en": "Description of category to import"
      },
      "parent": {
        "typeId": "category",
        "key": "key-of-parent-category"
      }
    }
  ]
}

CustomerImportRequest

The request body to import Customers. Contains data for Customers to be created or updated in a Project.
type​
customer

The resource types that can be imported.

resources​
Array of CustomerImport​

The customer import resources of this request.

MaxItems: 20​
Example: json
{
  "type": "customer",
  "resources": [
    {
      "key": "customer-to-import",
      "customerNumber": "12345",
      "email": "john@example.com",
      "password": "D0cEx@mpl3!2025",
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1980-01-01",
      "isEmailVerified": false,
      "externalId": "external-id-123",
      "customerGroup": {
        "typeId": "customer-group",
        "key": "customer-group-key"
      },
      "addresses": [
        {
          "key": "john-doe-address-key",
          "streetName": "Main Street",
          "streetNumber": "123",
          "postalCode": "12345",
          "city": "Berlin",
          "country": "DE"
        }
      ],
      "authenticationMode": "Password"
    }
  ]
}

DiscountCodeImportRequest

The request body to import DiscountCodes. Contains data for Discount Codes to be created or updated in a Project.
type​
discount-code

The resource types that can be imported.

resources​
Array of DiscountCodeImport​

The Discount Code import resources of this request.

MaxItems: 20​
Example: json
{
  "type": "discount-code",
  "resources": [
    {
      "key": "discountCodeKey",
      "code": "Save10",
      "name": {
        "en": "Save10"
      },
      "cartDiscounts": [
        {
          "typeId": "cart-discount",
          "key": "cartDiscountKey"
        }
      ],
      "isActive": false,
      "groups": []
    }
  ]
}

EmbeddedPriceImportRequest

The request body to import Embedded Prices. Contains data for Embedded Prices to be created or updated in a Project.
type​
price

The resource types that can be imported.

resources​
Array of PriceImport​

The price import resources of this request.

MaxItems: 20​
Example: json
{
  "type": "price",
  "resources": [
    {
      "key": "price-key",
      "country": "DE",
      "validFrom": "2021-04-11T14:00:00.000Z",
      "validUntil": "2022-04-11T14:00:00.000Z",
      "customerGroup": {
        "typeId": "customer-group",
        "key": "customer-group-key"
      },
      "channel": {
        "typeId": "channel",
        "key": "channel-key"
      },
      "productVariant": {
        "typeId": "product-variant",
        "key": "red-t-shirt"
      },
      "product": {
        "typeId": "product",
        "key": "t-shirt"
      },
      "value": {
        "type": "centPrecision",
        "currencyCode": "EUR",
        "centAmount": 300
      }
    }
  ]
}

InventoryImportRequest

The request body to import Inventories. Contains data for InventoryEntries to be created or updated in a commercetools Project.
type​
inventory

The resource types that can be imported.

resources​
Array of InventoryImport​

The inventory import resources of this request.

MaxItems: 20​
Example: json
{
  "type": "inventory",
  "resources": [
    {
      "key": "inventory-import-key",
      "sku": "product-variant-sku",
      "quantityOnStock": 15,
      "restockableInDays": 2,
      "expectedDelivery": "2022-06-30T14:00:00.000Z",
      "supplyChannel": {
        "typeId": "channel",
        "key": "channel-key"
      }
    }
  ]
}

StandalonePriceImportRequest

The request body to import Standalone Prices. Contains data for Standalone Prices to be created or updated in a Project.
type​
standalone-price

The resource types that can be imported.

resources​
Array of StandalonePriceImport​

The Standalone Price import resources of this request.

MaxItems: 20​
Example: json
{
  "type": "standalone-price",
  "resources": [
    {
      "key": "standalone-price-key",
      "sku": "variantSku",
      "value": {
        "type": "centPrecision",
        "currencyCode": "EUR",
        "centAmount": 100
      }
    }
  ]
}

OrderImportRequest

The request body to import Orders. Contains data for Orders to be created in a Project.
type​
order

The resource types that can be imported.

resources​
Array of OrderImport​

The order import resources of this request.

MaxItems: 20​
Example: json
{
  "type": "order",
  "resources": [
    {
      "orderNumber": "order-number",
      "customer": {
        "typeId": "customer",
        "key": "order-customer-key"
      },
      "lineItems": [
        {
          "name": {
            "en": "abc"
          },
          "quantity": 10,
          "price": {
            "value": {
              "type": "centPrecision",
              "centAmount": 100,
              "currencyCode": "EUR"
            }
          },
          "supplyChannel": {
            "typeId": "channel",
            "key": "supplier-channel-key"
          },
          "variant": {
            "productVariant": {
              "typeId": "product-variant",
              "key": "product-key"
            },
            "sku": "variant-sku"
          }
        }
      ],
      "customerGroup": {
        "typeId": "customer-group",
        "key": "customer-group-key"
      },
      "totalPrice": {
        "type": "centPrecision",
        "currencyCode": "EUR",
        "centAmount": 4200
      }
    }
  ]
}

OrderPatchImportRequest

The request body to import OrderPatches. The data to be imported are represented by OrderPatchImport.
type​
order-patch

The resource types that can be imported.

patches​
Array of OrderPatchImport​

The order patches of this request

MaxItems: 20​
Example: json
{
  "type": "order-patch",
  "patches": [
    {
      "orderNumber": "order-number",
      "fields": {
        "addReturnInfo": {
          "items": [
            {
              "quantity": 1,
              "lineItemId": "1",
              "comment": "any comment",
              "shipmentState": "Advised"
            }
          ],
          "returnTrackingId": "returnTrackingId-example",
          "returnDate": "2021-04-30T09:21:15.003Z"
        },
        "addDeliveries": [
          {
            "items": [
              {
                "id": "4ce24c27-cce5-447c-890e-0d6b70b690be",
                "quantity": 5
              }
            ],
            "parcels": [
              {
                "measurements": {
                  "heightInMillimeter": 20,
                  "lengthInMillimeter": 40,
                  "widthInMillimeter": 5,
                  "weightInGram": 10
                }
              }
            ]
          }
        ],
        "removeDelivery": {
          "id": "95a6e7a7-b74e-4397-b0b4-37473d2e3573"
        },
        "removeParcelFromDelivery": {
          "parcelId": "98840afa-ac20-4a34-a904-88d3407e2d76"
        },
        "addParcelToDelivery": {
          "deliveryId": "95a6e7a7-b74e-4397-b0b4-37473d2e3573",
          "measurements": {
            "heightInMillimeter": 20,
            "lengthInMillimeter": 40,
            "widthInMillimeter": 5,
            "weightInGram": 10
          }
        },
        "setParcelMeasurements": {
          "parcelId": "98840afa-ac20-4a34-a904-88d3407e2d76",
          "measurements": {
            "heightInMillimeter": 20,
            "lengthInMillimeter": 40,
            "widthInMillimeter": 5,
            "weightInGram": 10
          }
        },
        "setParcelTrackingData": {
          "parcelId": "98840afa-ac20-4a34-a904-88d3407e2d76",
          "trackingData": {
            "carrier": "carrier data"
          }
        },
        "setParcelItems": [
          {
            "parcelId": "98840afa-ac20-4a34-a904-88d3407e2d76",
            "items": [
              {
                "id": "4ce24c27-cce5-447c-890e-0d6b70b690be",
                "quantity": 5
              }
            ]
          }
        ]
      }
    }
  ]
}

ProductTypeImportRequest

The request body to import ProductTypes. Contains data for ProductTypes to be created or updated in a Project.
type​
product-type

The resource types that can be imported.

resources​
Array of ProductTypeImport​

The product type import resources of this request.

MaxItems: 20​
Example: json
{
  "type": "product-type",
  "resources": [
    {
      "key": "product-type-key",
      "name": "Product Type name",
      "description": "Test product type",
      "attributes": [
        {
          "name": "product-ref-attribute",
          "label": {
            "en": "selling product"
          },
          "isRequired": false,
          "isSearchable": false,
          "type": {
            "name": "reference",
            "referenceTypeId": "category"
          },
          "attributeConstraint": "Unique",
          "inputTip": {
            "en": "product input tip"
          },
          "inputHint": "SingleLine"
        }
      ]
    }
  ]
}

ProductImportRequest

The request body to import Products. Contains data for Products to be created or updated in a Project.
type​
product

The resource types that can be imported.

resources​
Array of ProductImport​

The product import resources of this request.

MaxItems: 20​
Example: json
{
  "type": "product",
  "resources": [
    {
      "key": "product-key",
      "name": {
        "en": "t-shirt"
      },
      "productType": {
        "typeId": "product-type",
        "key": "product-type-key"
      },
      "slug": {
        "en": "t-shirt-slug"
      },
      "description": {
        "en": "t-shirt-description"
      },
      "categories": [
        {
          "typeId": "category",
          "key": "category-key"
        }
      ],
      "taxCategory": {
        "typeId": "tax-category",
        "key": "tax-category-key"
      },
      "state": {
        "typeId": "state",
        "key": "state-key"
      }
    }
  ]
}

ProductDraftImportRequest

The request body to import ProductDrafts. Contains data for Products to be created or updated in a Project.
type​
product-draft

The resource types that can be imported.

resources​
Array of ProductDraftImport​

The product draft import resources of this request.

MaxItems: 20​
Example: json
{
  "type": "product-draft",
  "resources": [
    {
      "key": "product-draft-key",
      "name": {
        "en": "blue shirt"
      },
      "slug": {
        "en": "blue-t-shirt"
      },
      "productType": {
        "typeId": "product-type",
        "key": "sample"
      },
      "masterVariant": {
        "key": "master-variant-key",
        "attributes": [
          {
            "type": "reference",
            "name": "product-ref-attribute",
            "value": {
              "key": "category-key",
              "typeId": "category"
            }
          },
          {
            "type": "reference",
            "name": "product-custom-object-ref-attribute",
            "value": {
              "key": "custom-object-key",
              "container": "custom-object-container-key",
              "typeId": "key-value-document"
            }
          }
        ]
      }
    }
  ]
}

ProductVariantImportRequest

The request body to import ProductVariants. Contains data for ProductVariants to be created or updated in a Project.
type​
product-variant

The resource types that can be imported.

resources​
Array of ProductVariantImport​

The product variant import resources of this request.

MaxItems: 20​
Example: json
{
  "type": "product-variant",
  "resources": [
    {
      "key": "red-t-shirt",
      "sku": "red-t-shirt",
      "product": {
        "key": "t-shirt",
        "typeId": "product"
      },
      "isMasterVariant": true,
      "attributes": [
        {
          "name": "new",
          "type": "boolean",
          "value": true
        },
        {
          "name": "weight",
          "type": "number",
          "value": 12.5
        }
      ]
    }
  ]
}

ProductVariantPatchRequest

The request body to import ProductVariantPatches. The data to be imported are represented by ProductVariantPatch.
type​
product-variant-patch

The resource types that can be imported.

patches​
Array of ProductVariantPatch​

The product variant patches of this request.

MaxItems: 20​
Example: json
{
  "type": "product-variant-patch",
  "patches": [
    {
      "productVariant": {
        "typeId": "product-variant",
        "key": "red-t-shirt"
      },
      "attributes": {
        "attribute-to-update": {
          "type": "boolean",
          "value": true
        },
        "name-of-attribute-to-delete": null,
        "name-of-localized-attribute-to-update": {
          "type": "ltext",
          "value": {
            "en": "Existing field",
            "es": null,
            "de": "Updating field"
          }
        },
        "name-of-localized-attribute-set-to-update": {
          "type": "ltext-set",
          "value": [
            {
              "en": "Existing field",
              "es": null,
              "de": "Updating field",
              "br": "New field"
            },
            {
              "en": "Another Existing field",
              "es": null,
              "de": "Another Updating field",
              "br": "Another New field"
            }
          ]
        }
      },
      "staged": false
    }
  ]
}

ProductSelectionImportRequest

The request body to import Product Selections. Contains data for Product Selections to be created or updated in a Project.
type​
product-selection

The resource types that can be imported.

resources​
Array of ProductSelectionImport​

The Product Selection import resources of this request.

MaxItems: 20​
Example: json
{
  "type": "product-selection",
  "resources": [
    {
      "key": "selection-001",
      "name": {
        "en": "Featured Products",
        "de": "Empfohlene Produkte"
      },
      "mode": "Individual",
      "assignments": [
        {
          "product": {
            "key": "product-123",
            "typeId": "product"
          },
          "variantSelection": {
            "type": "includeOnly",
            "skus": [
              "SKU-1",
              "SKU-2"
            ]
          }
        }
      ]
    }
  ]
}

TypeImportRequest

The request body to import Types. Contains data for Types to be created or updated in a Project.
type​
type

The resource types that can be imported.

resources​
Array of TypeImport​

The type import resources of this request.

MaxItems: 20​
Example: json
{
  "type": "type",
  "resources": [
    {
      "key": "type-key",
      "name": {
        "en": "Name of type"
      },
      "description": {
        "en": "Description of type"
      },
      "resourceTypeIds": [
        "customer"
      ],
      "fieldDefinitions": [
        {
          "type": {
            "name": "String"
          },
          "name": "exampleStringField",
          "label": {
            "en": "Example string field."
          },
          "required": false,
          "inputHint": "SingleLine"
        }
      ]
    }
  ]
}

ImportResponse

The response of each Import Request.

operationStatus​
Array of ImportOperationStatus​
The identifiers and status of the ImportOperations created by the ImportRequest.
MaxItems: 20​
Example: json
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

Create Import Request

for Categories

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

Creates an Import Request for Categories.

OAuth 2.0 Scopes:
manage_products:{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 to send this ImportRequest.
Request Body:CategoryImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/categories/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "category",
  "resources" : [ {
    "key" : "category-to-import",
    "name" : {
      "en" : "Category to import"
    },
    "slug" : {
      "en" : "category-to-import-slug"
    },
    "description" : {
      "en" : "Description of category to import"
    },
    "parent" : {
      "typeId" : "category",
      "key" : "key-of-parent-category"
    }
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Customers

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

Creates an Import Request for Customers.

OAuth 2.0 Scopes:
manage_customers:{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 to send this ImportRequest.
Request Body:CustomerImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/customers/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "customer",
  "resources" : [ {
    "key" : "customer-to-import",
    "customerNumber" : "12345",
    "email" : "john@example.com",
    "password" : "D0cEx@mpl3!2025",
    "firstName" : "John",
    "lastName" : "Doe",
    "dateOfBirth" : "1980-01-01",
    "isEmailVerified" : false,
    "externalId" : "external-id-123",
    "customerGroup" : {
      "typeId" : "customer-group",
      "key" : "customer-group-key"
    },
    "addresses" : [ {
      "key" : "john-doe-address-key",
      "streetName" : "Main Street",
      "streetNumber" : "123",
      "postalCode" : "12345",
      "city" : "Berlin",
      "country" : "DE"
    } ],
    "authenticationMode" : "Password"
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Discount Codes

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

Creates an Import Request for Discount Codes.

OAuth 2.0 Scopes:
manage_discount_codes:{projectKey}view_discount_codes:{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 to send this ImportRequest.
Request Body:DiscountCodeImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/discount-codes/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "discount-code",
  "resources" : [ {
    "key" : "discountCodeKey",
    "code" : "Save10",
    "name" : {
      "en" : "Save10"
    },
    "cartDiscounts" : [ {
      "typeId" : "cart-discount",
      "key" : "cartDiscountKey"
    } ],
    "isActive" : false,
    "groups" : [ ]
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Embedded Prices

To create and update Standalone Prices, use the Standalone Prices endpoint instead.
POST
https://import.{region}.commercetools.com/{projectKey}/prices/import-containers/{importContainerKey}

Creates an Import Request for Prices.

OAuth 2.0 Scopes:
manage_products:{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 to send this ImportRequest.
Request Body:PriceImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/prices/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "price",
  "resources" : [ {
    "key" : "price-key",
    "country" : "DE",
    "validFrom" : "2021-04-11T14:00:00.000Z",
    "validUntil" : "2022-04-11T14:00:00.000Z",
    "customerGroup" : {
      "typeId" : "customer-group",
      "key" : "customer-group-key"
    },
    "channel" : {
      "typeId" : "channel",
      "key" : "channel-key"
    },
    "productVariant" : {
      "typeId" : "product-variant",
      "key" : "red-t-shirt"
    },
    "product" : {
      "typeId" : "product",
      "key" : "t-shirt"
    },
    "value" : {
      "type" : "centPrecision",
      "currencyCode" : "EUR",
      "centAmount" : 300
    }
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Inventory

This endpoint can be used to import inventory data to create and update InventoryEntry in a Project.
POST
https://import.{region}.commercetools.com/{projectKey}/inventories/import-containers/{importContainerKey}

Creates an Import Request for InventoryEntries.

OAuth 2.0 Scopes:
manage_products:{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 to send this ImportRequest.
Request Body:InventoryImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/inventories/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "inventory",
  "resources" : [ {
    "key" : "inventory-import-key",
    "sku" : "product-variant-sku",
    "quantityOnStock" : 15,
    "restockableInDays" : 2,
    "expectedDelivery" : "2022-06-30T14:00:00.000Z",
    "supplyChannel" : {
      "typeId" : "channel",
      "key" : "channel-key"
    }
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Products

This endpoint can be used to import Product data without Product Variant or Price information.

To import Product data with Product Variants and Prices in one import request, the ProductDraft Import endpoint is available. As this endpoint has a smaller payload compared to the ProductDraft Import endpoint, a faster performance can be expected since Product Variant and Price information is not involved.
POST
https://import.{region}.commercetools.com/{projectKey}/products/import-containers/{importContainerKey}

Creates an Import Request for Products.

OAuth 2.0 Scopes:
manage_products:{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 to send this ImportRequest.
Request Body:ProductImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/products/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "product",
  "resources" : [ {
    "key" : "product-key",
    "name" : {
      "en" : "t-shirt"
    },
    "productType" : {
      "typeId" : "product-type",
      "key" : "product-type-key"
    },
    "slug" : {
      "en" : "t-shirt-slug"
    },
    "description" : {
      "en" : "t-shirt-description"
    },
    "categories" : [ {
      "typeId" : "category",
      "key" : "category-key"
    } ],
    "taxCategory" : {
      "typeId" : "tax-category",
      "key" : "tax-category-key"
    },
    "state" : {
      "typeId" : "state",
      "key" : "state-key"
    }
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Product Drafts

This endpoint allows you to import Products as well as Product Variants and Embedded Prices in a single import request. While using this endpoint (instead of calling three separate endpoints for Products, Product Variants, and Embedded Prices) reduces the number of API calls, this single request requires a relatively large payload.

When importing a Product Draft to update an existing Product, you must include all existing values for fields or they will be removed when the Product Draft is imported.

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

Creates an Import Request for Products.

OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
​
String
​
The Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
importContainerKey
​
String
​

The ImportContainer used to create the new resource

Request Body:ProductDraftImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/product-drafts/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "product-draft",
  "resources" : [ {
    "key" : "product-draft-key",
    "name" : {
      "en" : "blue shirt"
    },
    "slug" : {
      "en" : "blue-t-shirt"
    },
    "productType" : {
      "typeId" : "product-type",
      "key" : "sample"
    },
    "masterVariant" : {
      "key" : "master-variant-key",
      "attributes" : [ {
        "type" : "reference",
        "name" : "product-ref-attribute",
        "value" : {
          "key" : "category-key",
          "typeId" : "category"
        }
      }, {
        "type" : "reference",
        "name" : "product-custom-object-ref-attribute",
        "value" : {
          "key" : "custom-object-key",
          "container" : "custom-object-container-key",
          "typeId" : "key-value-document"
        }
      } ]
    }
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Product Types

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

Creates an Import Request for ProductTypes.

OAuth 2.0 Scopes:
manage_products:{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 to send this ImportRequest.
Request Body:ProductTypeImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/product-types/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "product-type",
  "resources" : [ {
    "key" : "product-type-key",
    "name" : "Product Type name",
    "description" : "Test product type",
    "attributes" : [ {
      "name" : "product-ref-attribute",
      "label" : {
        "en" : "selling product"
      },
      "isRequired" : false,
      "isSearchable" : false,
      "type" : {
        "name" : "reference",
        "referenceTypeId" : "category"
      },
      "attributeConstraint" : "Unique",
      "inputTip" : {
        "en" : "product input tip"
      },
      "inputHint" : "SingleLine"
    } ]
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Product Variants

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

Creates an Import Request for ProductVariants.

OAuth 2.0 Scopes:
manage_products:{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 to send this ImportRequest.
Request Body:ProductVariantImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/product-variants/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "product-variant",
  "resources" : [ {
    "key" : "red-t-shirt",
    "sku" : "red-t-shirt",
    "product" : {
      "key" : "t-shirt",
      "typeId" : "product"
    },
    "isMasterVariant" : true,
    "attributes" : [ {
      "name" : "new",
      "type" : "boolean",
      "value" : true
    }, {
      "name" : "weight",
      "type" : "number",
      "value" : 12.5
    } ]
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Product Variant Patches

The Product Variant Patch endpoint can be used to update existing Product Variants in a Project. For importing new Product Variants, use the Product Variants endpoint.
POST
https://import.{region}.commercetools.com/{projectKey}/product-variant-patches/import-containers/{importContainerKey}
Creates an Import Request for updating Product Variants. Returns an InvalidField error if the ProductVariantPatchRequest contains patches with and without the product field set.
OAuth 2.0 Scopes:
manage_products:{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 to send this ImportRequest.
Request Body:ProductVariantPatchRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/product-variant-patches/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "product-variant-patch",
  "patches" : [ {
    "productVariant" : {
      "typeId" : "product-variant",
      "key" : "red-t-shirt"
    },
    "attributes" : {
      "attribute-to-update" : {
        "type" : "boolean",
        "value" : true
      },
      "name-of-attribute-to-delete" : null,
      "name-of-localized-attribute-to-update" : {
        "type" : "ltext",
        "value" : {
          "en" : "Existing field",
          "es" : null,
          "de" : "Updating field"
        }
      },
      "name-of-localized-attribute-set-to-update" : {
        "type" : "ltext-set",
        "value" : [ {
          "en" : "Existing field",
          "es" : null,
          "de" : "Updating field",
          "br" : "New field"
        }, {
          "en" : "Another Existing field",
          "es" : null,
          "de" : "Another Updating field",
          "br" : "Another New field"
        } ]
      }
    },
    "staged" : false
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Product Selections

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

Creates an Import Request for Product Selections.

OAuth 2.0 Scopes:
manage_product_selections:{projectKey}view_product_selections:{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 to send this ImportRequest.
Request Body:ProductSelectionImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/product-selections/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "product-selection",
  "resources" : [ {
    "key" : "selection-001",
    "name" : {
      "en" : "Featured Products",
      "de" : "Empfohlene Produkte"
    },
    "mode" : "Individual",
    "assignments" : [ {
      "product" : {
        "key" : "product-123",
        "typeId" : "product"
      },
      "variantSelection" : {
        "type" : "includeOnly",
        "skus" : [ "SKU-1", "SKU-2" ]
      }
    } ]
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Orders

This endpoint can be used to create Orders in a Project in bulks.
To import a single Order, you can use the Create Order by Import endpoint instead.
POST
https://import.{region}.commercetools.com/{projectKey}/orders/import-containers/{importContainerKey}

Creates an Import Request for creating Orders.

OAuth 2.0 Scopes:
manage_orders:{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 to send this ImportRequest.
Request Body:OrderImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/orders/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "order",
  "resources" : [ {
    "orderNumber" : "order-number",
    "customer" : {
      "typeId" : "customer",
      "key" : "order-customer-key"
    },
    "lineItems" : [ {
      "name" : {
        "en" : "abc"
      },
      "quantity" : 10,
      "price" : {
        "value" : {
          "type" : "centPrecision",
          "centAmount" : 100,
          "currencyCode" : "EUR"
        }
      },
      "supplyChannel" : {
        "typeId" : "channel",
        "key" : "supplier-channel-key"
      },
      "variant" : {
        "productVariant" : {
          "typeId" : "product-variant",
          "key" : "product-key"
        },
        "sku" : "variant-sku"
      }
    } ],
    "customerGroup" : {
      "typeId" : "customer-group",
      "key" : "customer-group-key"
    },
    "totalPrice" : {
      "type" : "centPrecision",
      "currencyCode" : "EUR",
      "centAmount" : 4200
    }
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Order Patches

The Order Patch endpoint can be used to import updates to ReturnInfo, Parcel, and Delivery of an existing Order.
POST
https://import.{region}.commercetools.com/{projectKey}/order-patches/import-containers/{importContainerKey}

Creates an Import Request for updating Orders.

OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
​
String
​
The Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
importContainerKey
​
String
​

The ImportContainer used to create the resource

Request Body:OrderPatchImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/order-patches/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "order-patch",
  "patches" : [ {
    "orderNumber" : "order-number",
    "fields" : {
      "addReturnInfo" : {
        "items" : [ {
          "quantity" : 1,
          "lineItemId" : "1",
          "comment" : "any comment",
          "shipmentState" : "Advised"
        } ],
        "returnTrackingId" : "returnTrackingId-example",
        "returnDate" : "2021-04-30T09:21:15.003Z"
      },
      "addDeliveries" : [ {
        "items" : [ {
          "id" : "4ce24c27-cce5-447c-890e-0d6b70b690be",
          "quantity" : 5
        } ],
        "parcels" : [ {
          "measurements" : {
            "heightInMillimeter" : 20,
            "lengthInMillimeter" : 40,
            "widthInMillimeter" : 5,
            "weightInGram" : 10
          }
        } ]
      } ],
      "removeDelivery" : {
        "id" : "95a6e7a7-b74e-4397-b0b4-37473d2e3573"
      },
      "removeParcelFromDelivery" : {
        "parcelId" : "98840afa-ac20-4a34-a904-88d3407e2d76"
      },
      "addParcelToDelivery" : {
        "deliveryId" : "95a6e7a7-b74e-4397-b0b4-37473d2e3573",
        "measurements" : {
          "heightInMillimeter" : 20,
          "lengthInMillimeter" : 40,
          "widthInMillimeter" : 5,
          "weightInGram" : 10
        }
      },
      "setParcelMeasurements" : {
        "parcelId" : "98840afa-ac20-4a34-a904-88d3407e2d76",
        "measurements" : {
          "heightInMillimeter" : 20,
          "lengthInMillimeter" : 40,
          "widthInMillimeter" : 5,
          "weightInGram" : 10
        }
      },
      "setParcelTrackingData" : {
        "parcelId" : "98840afa-ac20-4a34-a904-88d3407e2d76",
        "trackingData" : {
          "carrier" : "carrier data"
        }
      },
      "setParcelItems" : [ {
        "parcelId" : "98840afa-ac20-4a34-a904-88d3407e2d76",
        "items" : [ {
          "id" : "4ce24c27-cce5-447c-890e-0d6b70b690be",
          "quantity" : 5
        } ]
      } ]
    }
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Standalone Prices

This endpoint can be used to import Standalone Price data to create and update Standalone Prices in a Project.
To create and update Embedded Prices, use the Embedded Prices endpoint instead.
POST
https://import.{region}.commercetools.com/{projectKey}/standalone-prices/import-containers/{importContainerKey}

Creates an Import Request for Standalone Prices.

OAuth 2.0 Scopes:
manage_standalone_prices:{projectKey}view_standalone_prices:{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 to send this ImportRequest.
Request Body:StandalonePriceImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/standalone-prices/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "standalone-price",
  "resources" : [ {
    "key" : "standalone-price-key",
    "sku" : "variantSku",
    "value" : {
      "type" : "centPrecision",
      "currencyCode" : "EUR",
      "centAmount" : 100
    }
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}

for Types

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

Creates an Import Request for Types.

OAuth 2.0 Scopes:
manage_project:{projectKey}manage_types:{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 to send this ImportRequest.
Request Body:TypeImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json
Request Example:cURL
curl https://import.{region}.commercetools.com/{projectKey}/types/import-containers/{importContainerKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "type" : "type",
  "resources" : [ {
    "key" : "type-key",
    "name" : {
      "en" : "Name of type"
    },
    "description" : {
      "en" : "Description of type"
    },
    "resourceTypeIds" : [ "customer" ],
    "fieldDefinitions" : [ {
      "type" : {
        "name" : "String"
      },
      "name" : "exampleStringField",
      "label" : {
        "en" : "Example string field."
      },
      "required" : false,
      "inputHint" : "SingleLine"
    } ]
  } ]
}
DATA
201 Response Example: ImportResponsejson
{
  "operationStatus": [
    {
      "state": "processing",
      "operationId": "252c6ed3-c668-4610-afe9-87b9255e62e0"
    }
  ]
}