Documentation
BETA

Importing Products

Elevate, May 20-22-2025, Miami Beach, Florida
Create and update Products without Product Variant or Embedded Price data.
The data to import is represented by ProductImport and included in a ProductImportRequest, which is imported using Import Products.
If you need to import Products with Product Variant and Embedded Price data, use ProductDraft Import. For more information, see Choose the right Product import endpoint.
When importing Product data to update an existing Product, you must include existing values for fields (for example categories and taxCategory) or they will be removed when the Product is imported.

Representations

ProductImportRequest

The request body to import Products. Contains data for Products to be created or updated in a Project.
type​
ImportResourceType​
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": "t-shirt",
      "name": {
        "en": "t-shirt"
      },
      "productType": {
        "typeId": "product-type",
        "key": "sample"
      },
      "slug": {
        "en": "t-shirt-slug"
      },
      "description": {
        "en": "t-shirt-description"
      },
      "categories": [
        {
          "typeId": "category",
          "key": "greatTestCat"
        }
      ],
      "metaTitle": {
        "en": "title"
      },
      "metaDescription": {
        "en": "description"
      },
      "metaKeywords": {
        "en": "Keywords"
      },
      "taxCategory": {
        "typeId": "tax-category",
        "key": "tax-category-key"
      },
      "state": {
        "typeId": "state",
        "key": "state-key"
      }
    }
  ]
}

ProductImport

The data representation for a Product to be imported that is persisted as a Product in the Project.
This is the minimal representation required for creating a Product in commercetools.
key​
String​
User-defined unique identifier. If a Product with this key exists, it will be updated with the imported data.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
LocalizedString​
Maps to Product.name.
productType​
ProductTypeKeyReference​
The productType of a Product. Maps to Product.productType. The Reference to the ProductType with which the Product is associated. If referenced ProductType does not exist, the state of the ImportOperation will be set to unresolved until the necessary ProductType is created.
slug​
LocalizedString​

Human-readable identifiers usually used as deep-link URL to the related product. Each slug must be unique across a Project, but a product can have the same slug for different languages. Allowed are alphabetic, numeric, underscore (_) and hyphen (-) characters.

description​
LocalizedString​
Maps to Product.description.
categories​
Array of CategoryKeyReference​
Maps to Product.categories. The References to the Categories with which the Product is associated. If referenced Categories do not exist, the state of the ImportOperation will be set to unresolved until the necessary Categories are created.
metaTitle​
LocalizedString​
metaDescription​
LocalizedString​
metaKeywords​
LocalizedString​
taxCategory​
TaxCategoryKeyReference​
The Reference to the TaxCategory with which the Product is associated. If referenced TaxCategory does not exist, the state of the ImportOperation will be set to unresolved until the necessary TaxCategory is created.
searchKeywords​
SearchKeywords​
state​
StateKeyReference​
The Reference to the State with which the Product is associated. If referenced State does not exist, the state of the ImportOperation will be set to unresolved until the necessary State is created.
publish​
Boolean​
Determines the published status and current/staged projection of the Product. For more information, see Managing the published state of Products.
priceMode​
ProductPriceModeEnum​
Determines the type of Prices the API uses. If not provided, the existing Product.priceMode is not changed.

Import Products

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

Creates a request for creating new Products or updating existing ones.

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

The Project key.

importContainerKey
​
String
​

The ImportContainer used to create the new resource

Request Body:ProductImportRequestasapplication/json
Response:
201

ImportResponse

asapplication/json