Product import

Learn about the headers and values supported for importing Products.

When importing Products, you can select the Publish all products in the file checkbox to update the current and staged representation of existing Products, and publish new Products. If not selected, the imported data will only update the staged representation of existing Products and new Products created by the import process are not published.

Prerequisites

Products require a Product Type. You cannot create Product Types by CSV import. As a result, you must create Product Types beforehand from the Merchant Center or by using the HTTP API. Each Product Type must have a key.

Supported headers and values

Products

When importing the complete Product data as one large CSV file, you can also include the headers and values from Prices, Price tiers, Assets, and Images.

You can update a Product only if it has a key. You can assign a key to a Product either from the Product list or by using the Products API.

When updating Products, include only the headers and values for the fields you are updating.

Header	Value	Required/Optional
`data-object`	An annotation for the data that is imported. It is ignored during import.	Optional
`key`	A unique identifier for the Product that is imported. The key must only include letters, numbers, underscores (_), or dashes (-). If a Product with the provided `key` exists in the Project, the Product is updated with the provided value—otherwise, a new Product is created.	Required
`productType.key`	A unique identifier for the Product Type that the imported Product belongs to.	Required, when creating a new Product.
`productType.typeId`	`product-type`	Required, if `productType.key` is provided.
`name.en`	A localized name for the Product. You can provide multiple headers to include different languages values. For headers ending with `.en`, you can change `en` to reference another language. For example, including the header `name.de` allows you to include a German name, and `name.en-US` allows you to include an English (American) name.	Required, when creating a new Product.
`description.en`	A localized description for the Product. You can provide multiple headers to include different languages values. For headers ending with `.en`, you can change `en` to reference another language. For example, including the header `name.de` allows you to include a German name, and `name.en-US` allows you to include an English (American) name.	Optional
`categories`	A unique identifier for a Category to assign the Product to. To assign to multiple Categories, separate the keys with a semicolon.	Optional
`slug.en`	A localized slug for the Product. You can provide multiple headers to include different languages values. For headers ending with `.en`, you can change `en` to reference another language. For example, including the header `name.de` allows you to include a German name, and `name.en-US` allows you to include an English (American) name.	Required, when creating a new Product.
`searchKeywords.en`	A list of localized keywords—separated by a semicolon—for search engines. You can provide multiple headers to include different languages values. For headers ending with `.en`, you can change `en` to reference another language. For example, including the header `name.de` allows you to include a German name, and `name.en-US` allows you to include an English (American) name.	Optional
`state.key`	A unique identifier for the State the Product should transition to.	Optional
`state.typeId`	`state`	Required, if `state.key` is provided.
`metaTitle.en`	A localized name for the Product for search engines. You can provide multiple headers to include different languages values. For headers ending with `.en`, you can change `en` to reference another language. For example, including the header `name.de` allows you to include a German name, and `name.en-US` allows you to include an English (American) name.	Optional
`metaDescription.en`	A localized description for the Product for search engines. You can provide multiple headers to include different languages values. For headers ending with `.en`, you can change `en` to reference another language. For example, including the header `name.de` allows you to include a German name, and `name.en-US` allows you to include an English (American) name.	Optional
`taxCategory.key`	A unique identifier for the Tax Category used by the Product.	Optional
`taxCategory.typeId`	`tax-category`	Required, if `taxCategory.key` is provided.
`priceMode`	The type of Price used by the Product—must be `Embedded` or `Standalone`.	Optional
`variants.sku`	A SKU for the Product Variant.	Optional
`variants.key`	A unique identifier for the Product Variant that is imported.	Required, when importing Product Variant data.
`attributes.{nameOfAttribute}`	Replace `{nameOfAttribute}` with the name of the Attribute. Attribute names are case-sensitive. The value must conform to the type of the Attribute. For more information, see Attributes.	Optional

Attributes

All Attributes—except nested Attributes—are supported.

For boolean Attributes, the values must be lowercase.

Replace {nameOfAttribute} with the name of the Attribute. Attribute names are case-sensitive.

For Reference Attributes, provide the following additionally:

Header	Value	Required/Optional
`attributes.{nameOfAttribute}.key`	The `key` of the referenced resource.	Required
`attributes.{nameOfAttribute}.typeId`	The name of the reference resource. To know about the supported resources and their values, see AttributeReferenceTypeId.	Required

For Money Attributes, provide the following additionally:

Header	Value	Required/Optional
`attributes.{nameOfAttribute}.currencyCode`	An ISO 4217-compliant currency code such as `USD`, `EUR`, or `GBP`.	Required
`attributes.{nameOfAttribute}.centAmount`	An amount in the smallest indivisible unit for a currency. For example, `500` would be equal to USD 5.00 or JPY 500.	Required
`attributes.{nameOfAttribute}.type`	`centPrecision`	Required
`attributes.{nameOfAttribute}.fractionDigits`	The number of digits after a decimal separator. For example, `2` for USD or `0` for JPY.	Required

Sets of Attributes

For sets of simple Attribute types (such as numbers, text, and booleans) the header would contain the Attribute name, and value would be a semicolon-separated list. The following example demonstrates how to import sets of text and numbers.

`attributes.colorCombination`	`attributes.numberSet`
`red;green;blue`	`10;5;32`

Sets of complex Attribute types

For sets of complex values (such as localized text, references, and money), you can import single set values by defining the index then subfields in the header. The following example demonstrates how to update the first entry of a set of Attributes called relatedCategories that references Categories.

`attributes.relatedCategories.1.key`	`attributes.relatedCategories.1.typeId`
`red-shirts`	`category`

To update the second entry, include the same headers but change the 1 to 2.

You can also import multiple set values by using * instead of a number. With this approach, the values of set items are entered into sequential rows.

The following example demonstrates how to create a set of Attributes called relatedCategories with four entries.

`attributes.relatedCategories.*.key`	`attributes.relatedCategories.*.typeId`
`red-shirts`	`category`
`summer-collection`	`category`
`new-arrivals`	`category`
`red-accessories`	`category`

Prices

Prices require an existing Product that contains at least one Product Variant.

To update an existing price, the price must have a key.

You can update a Price only if the Price has a key. You can assign a key to a Price by using the Products API.

Header	Value	Required/Optional
`key`	A unique identifier for the Product that is imported. The key must only include letters, numbers, underscores (_), or dashes (-). If a Product with the provided `key` exists in the Project, the Product is updated with the provided value—otherwise, a new Product is created.	Required
`variants.sku`	A SKU for the Product Variant.	Optional
`variants.key`	A unique identifier for the Product Variant to add the Price to.	Required
`variants.prices.key`	A unique identifier for the Price, which must be unique for each Product Variant.	Required
`variants.prices.value.currencyCode`	An ISO 4217-compliant currency code such as `USD`, `EUR`, or `GBP`.	Required
`variants.prices.value.type`	`centPrecision` or `highPrecision`	Required
`variants.prices.value.centAmount`	An amount in the smallest indivisible unit for the provided currency. For example, `500` can be equal to USD 5.00 or JPY 500.	Required
`variants.prices.value.fractionDigits`	The number of digits after the decimal separator. For `centPrecision`, it is equal to the default number of fraction digits for a currency. For `highPrecision`, it is greater than the default number of fraction digits for a currency and it cannot be more than `20`.	Required
`variants.prices.value.preciseAmount`	An amount that is 1 / (10 ^ `fractionDigits`) of a currency.	Required, when `variants.prices.value.type` is `highPrecision`.
`variants.prices.country`	An ISO 3166-1 alpha-2-compliant code for the country in which the imported Price is valid, such as `US` or `JP`.	Optional
`variants.prices.customerGroup.key`	A Customer Group for which the imported Price is valid.	Optional
`variants.prices.customerGroup.typeId`	`customer-group`	Required, when `variants.prices.customerGroup.key` is provided.
`variants.prices.channel.key`	A Channel for which the imported Price is valid.	Optional
`variants.prices.channel.typeId`	`channel`	Required, when `variants.prices.channel.key` is provided.
`variants.prices.validFrom`	The date and time from when the imported Price is valid.	Optional
`variants.prices.validUntil`	The date and time until when the imported Price is valid.	Optional
`variants.prices.custom.type.key`	A unique identifier for the Type referenced in a Custom Field.	Required, when importing Custom Fields.
`variants.prices.custom.type.typeId`	`type`	Required, when `variants.prices.custom.type.key` is provided.
`variants.prices.custom.fields.{nameOfCustomField}`	Replace `{nameOfCustomField}` with the name of the Custom Field, as defined in the respective FieldDefinition. The value must conform to the FieldType of the Custom Field. For more information, see Custom Fields.	Optional

Custom Fields

Replace {nameOfCustomField} with the name of the Custom Field, as defined in the respective FieldDefinition. The name of the Custom Field is case-sensitive.

When importing LocalizedString Custom Fields, provide headers and values for each language. For example, for English and German, provide custom.fields.{nameOfCustomField}.en and custom.fields.{nameOfCustomField}.de respectively.

When importing boolean Custom Fields, the values must be lowercase.

For Money Custom Fields, provide the following additionally:

Header	Value	Required/Optional
`custom.fields.{nameOfCustomField}.currencyCode`	An ISO 4217-compliant currency code such as `USD`, `EUR`, or `GBP`.	Required
`custom.fields.{nameOfCustomField}.centAmount`	An amount in the smallest indivisible unit for a currency. For example, `500` can be equal to USD 5.00 or JPY 500.	Required
`custom.fields.{nameOfCustomField}.type`	`centPrecision`	Required
`custom.fields.{nameOfCustomField}.fractionDigits`	The number of digits after the decimal separator. For example, `2` for USD or `0` for JPY.	Required

Sets of Custom Fields

For sets of simple Custom Fields (such as numbers, text, and booleans) the header would contain the Custom Fields name, and value would be a semicolon-separated list. The following example demonstrates how to import sets of text and numbers.

`custom.fields.colorCombination`	`custom.fields.numberSet`
`red;green;blue`	`10;5;32`

Sets of complex Custom Fields

For sets of complex values (such as localized text, references, and money), you can import single set values by defining the index and the subfields in the header. The following example demonstrates how to update the first entry of a set of Custom Fields called relatedCategories that references Categories.

`custom.fields.relatedCategories.1.key`	`custom.fields.relatedCategories.1.typeId`
`red-shirts`	`category`

To update the second entry, include the same headers but change 1 to 2.

You can also import multiple set values by using * instead of a number. With this approach, the values of set items are entered into sequential rows.

The following example demonstrates how to create a set of Custom Fields called relatedCategories with four entries.

`custom.fields.relatedCategories.*.key`	`custom.fields.relatedCategories.*.typeId`
`red-shirts`	`category`
`summer-collection`	`category`
`new-arrivals`	`category`
`red-accessories`	`category`

Price tiers

Price tiers require an existing Product that contains at least one Product Variant.

Only adding and updating Price tiers is supported. You cannot delete Price tiers by CSV import.

You can update a Price tier only if the Price has a key. You can assign a key to a Price by using the Products API.

Header	Value	Required/Optional
`key`	A unique identifier for the Product that is imported. The key must only include letters, numbers, underscores (_), or dashes (-). If a Product with the provided `key` exists in the Project, the Product is updated with the provided value—otherwise, a new Product is created.	Required
`variants.key`	A unique identifier for the Product Variant to add the Price to.	Required
`variants.sku`	A SKU for the Product Variant.	Optional
`variants.prices.key`	A unique identifier for the Price to add the Price tier to, which must be unique for each Product Variant.	Required
`variants.prices.tiers.minimumQuantity`	The minimum quantity for which the imported Price tier is valid for. It must be greater than or equal to `2`. A Price cannot contain more than one tier with the same minimum quantity.	Required
`variants.prices.tiers.value.centAmount`	An amount in the smallest indivisible unit for the provided currency. For example, `500` can be equal to USD 5.00 or JPY 500.	Required
`variants.prices.tiers.value.currencyCode`	An ISO 4217-compliant currency code such as `USD`, `EUR`, or `GBP`.	Required
`variants.prices.tiers.value.type`	`centPrecision`	Required
`variants.prices.tiers.value.fractionDigits`	The number of digits after the decimal separator.	Required

Assets

Assets require an existing Product that contains at least one Product Variant.

You can update an Asset only if it has a key. You can assign a key to an Asset by using the Products API.

Header	Value	Required/Optional
`key`	A unique identifier for the Product that is imported. The key must only include letters, numbers, underscores (_), or dashes (-). If a Product with the provided `key` exists in the Project, the Product is updated with the provided value—otherwise, a new Product is created.	Required
`variants.sku`	An SKU for the Product Variant.	Optional
`variants.key`	A unique identifier for the Product Variant to add the Asset to.	Required
`variants.assets.key`	A unique identifier for the Asset.	Required
`variants.assets.name.en`	A localized name for the Asset. You can provide multiple headers to include different languages values. For headers ending with `.en`, you can change `en` to reference another language. For example, including the header `name.de` allows you to include a German name, and `name.en-US` allows you to include an English (American) name.	Required, when creating a new Asset.
`variants.assets.description.en`	A localized description for the Asset. You can provide multiple headers to include different languages values. For headers ending with `.en`, you can change `en` to reference another language. For example, including the header `name.de` allows you to include a German name, and `name.en-US` allows you to include an English (American) name.	Optional
`variants.assets.sources.uri`	A URI for the Asset.	Required, when creating a new Asset.
`variants.assets.tags`	A semicolon-separated list of keywords used for categorizing and organizing Assets.	Optional

Images

Images require an existing Product that contains at least one Product Variant.

Header	Value	Required/Optional
`key`	A unique identifier for the Product that is imported. The key must only include letters, numbers, underscores (_), or dashes (-). If a Product with the provided `key` exists in the Project, the Product is updated with the provided value—otherwise, a new Product is created.	Required
`variants.sku`	An SKU for the Product Variant.	Optional
`variants.key`	A unique identifier for the Product Variant to add the image to.	Required
`variants.images.url`	An URL for the image in its original size, which must be unique within a single Product Variant.	Required
`variants.images.label`	A custom label for the image.	Optional
`variants.images.dimensions.w`	The width (in pixels) of the image.	Required, when creating a new image.
`variants.images.dimensions.h`	The height (in pixels) of the image.	Required, when creating a new image.

Delete data

When updating resources, you can remove data for optional fields. To remove data, in the CSV file, enter [DELETE] as the value for the header (field). When deleting values for reference fields or multi-value fields, you must add a new column with the common prefix as the header, and enter [DELETE] as the value.

For example, to delete data for a Money Attribute—that is attributes.delivery-cost.currencyCode, attributes.delivery-cost.centAmount, attributes.delivery-cost.fractionDigits, and attributes.delivery-cost.type in the CSV file—add a new column, attributes.delivery-cost, with [DELETE] as its value.