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 Choosing the right Product import endpoint.

When importing Product Draft 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 Draft is imported.

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.

"product-draft"

The Product draft import resource type.

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": "greatTestCat",
"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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
productType

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
slug

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

Maps to Product.description.

categories

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
metaDescription
metaKeywords
masterVariant

The master Product variant. Required if the variants array contains a Product Variant.

variants

An array of related Product Variants.

taxCategory

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

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. See ProductPriceMode for more details. If not provided, the existing Product.priceMode is not changed.

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

EmbeddedPriceDraftImport

The representation of a Price Draft for the import purpose.

key
String

User-defined unique identifier for the Embedded Price.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
value
country
CountryCode

A two-digit country code as per ISO 3166-1 alpha-2.

customerGroup

References a customer group by key.

channel

References a channel by key.

validFrom
validUntil
discounted
DiscountedPrice

Sets a discounted price from an external service.

tiers
Array of PriceTier

The tiered prices for this price.

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:
201ImportResponseasapplication/json