Documentation
BETA

Importing Product Drafts

Create and update Products in your Project.
Use this endpoint to import Products, including their Product Variant and Embedded Price data.
The data to import is represented by ProductDraftImport and included in a ProductDraftImportRequest, which is imported using Import ProductDrafts.
This endpoint should only be used for large payloads containing complete Product data. If you do not need to import Product Variant or Embedded Price data, use ProductImport instead. For more information, see Choose the right Product import endpoint.
When updating an existing Product by import, you must include the existing values of all fields in ProductDraftImport. The import process will remove the values of omitted fields.
Read the Nested Attribute tutorial to learn how to create/update nested Attribute values with the commercetools Import API.

Representations

ProductDraftImportRequest

The request body to import ProductDrafts. Contains data for Products to be created or updated in a Project.
type​
ImportResourceType​
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"
            }
          }
        ]
      }
    }
  ]
}

ProductDraftImport

The representation of a Product Draft for the import purpose.

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_-]+$​
productType​
ProductTypeKeyReference​
The productType of a Product. Maps to Product.productType. The Reference to the ProductType with which the ProductDraft is associated. If referenced ProductType does not exist, the state of the ImportOperation will be set to unresolved until the necessary ProductType is created.
name​
LocalizedString​
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​
The Reference to the Categories with which the ProductDraft 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​
masterVariant​
ProductVariantDraftImport​
The master Product variant. Required if the variants array contains a Product Variant.
variants​
Array of ProductVariantDraftImport​

An array of related Product Variants.

taxCategory​
TaxCategoryKeyReference​
The Reference to the TaxCategory with which the ProductDraft 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 ProductDraft 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.
Default: false​
priceMode​
ProductPriceModeEnum​
Determines the type of Prices the API uses. If not provided, the existing Product.priceMode is not changed.
Example: json
{
  "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"
        }
      }
    ]
  }
}

ProductVariantDraftImport

The representation of a Product Variant Draft for the import purpose.

key​
String​
sku​
String​
prices​
Array of PriceDraftImport​
attributes​
Array of Attribute​
images​
Array of Image​
assets​
Array of Asset​

Attribute

This type represents the value of an attribute of a product variant. The name and type property must match the name and type property of an attribute definition of the product type.

name​
String​

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type​
String​

EmbeddedPriceDraftImport

The representation of a Price Draft for the import purpose.

key​
String​

User-defined unique identifier for the Embedded Price.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
value​
TypedMoney​
country​
CountryCode​
A two-digit country code as per ISO 3166-1 alpha-2.
customerGroup​
CustomerGroupKeyReference​

References a customer group by key.

channel​
ChannelKeyReference​

References a channel by key.

validFrom​
DateTime​
validUntil​
DateTime​
discounted​
DiscountedPrice​

Sets a discounted price from an external service.

tiers​
Array of PriceTier​

The tiered prices for this price.

custom​
Custom​

The custom fields for this category.

Import ProductDrafts

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

Creates a request for creating new ProductDrafts 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: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"
    }
  ]
}