Product import

Learn about the headers and values supported for importing Products.

Supported headers and values

Products

Products require a Product Type. You cannot create Product Types by CSV import so they must be created beforehand using the Merchant Center or HTTP API.

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.

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
`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`	Optional
`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. 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 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.

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

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.

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 then 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 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 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.

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.

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.0`	A keyword for categorizing and organizing Assets. You can include the header multiple times to include multiple tags by increasing the number—for example, `variants.assets.tags.1` and `variants.assets.tags.2`.	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.