Product Selection import

Learn about the headers and values supported for importing Product Selections from CSV files.

Product Selections let you group Products into named sets that Stores can offer to customers. A selection uses either an inclusion list (Individual mode) or an exclusion list (IndividualExclusion mode). Each assigned Product can further include or exclude specific Product Variants by SKU. To learn more, see Product Selection.

Prerequisites

An assignment references a Product by key. That Product must exist in the Project before the import runs.

Supported headers and values

Product Selections

You can update a Product Selection only if it has a key.

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

Header	Value	Required/Optional
`key`	A unique identifier for the Product Selection that is imported. The key must only include letters, numbers, underscores (_), or dashes (-). If a Product Selection with the provided `key` exists in the Project, it is updated with the provided values. Otherwise, a new entry is created.	Required
`name.en`	A localized name for the Product Selection. You can provide multiple headers to include different language 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 Selection.
`mode`	`Individual` or `IndividualExclusion`. In `Individual` mode, the selection is built from an inclusion list. In `IndividualExclusion` mode, the selection is built from an exclusion list. The mode is set when the Product Selection is created and cannot be changed afterward.	Optional. If not included, the default value is `Individual`.
`custom.type.key`	The key of the Type referenced in a Custom Field.	Required, when importing Custom Fields.
`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`

Product assignments

The value of mode determines which Variant headers apply to an assignment. Use assignments.variantSelection.* with Individual mode, and assignments.variantExclusion.skus with IndividualExclusion mode. An assignment cannot include both.

Any assignments.product.name header, such as assignments.product.name.en, is ignored on import. It appears in exported files to make the assigned Product identifiable.

Each assignment belongs to the Product Selection identified by key, whether it is new or already exists.

Header	Value	Required/Optional
`key`	A unique identifier for the Product Selection the assignment belongs to.	Required
`assignments.product.key`	A unique identifier for the Product to assign to the Product Selection.	Required, when importing an assignment.
`assignments.variantSelection.type`	`includeOnly` or `includeAllExcept`. With `includeOnly`, only the listed Variants are assigned. With `includeAllExcept`, all Variants except the listed ones are assigned. Applies to `Individual` mode.	Required, when specifying a variant selection.
`assignments.variantSelection.skus`	A semicolon-separated list of Product Variant SKUs that `assignments.variantSelection.type` applies to. Applies to `Individual` mode.	Required, when specifying a variant selection.
`assignments.variantExclusion.skus`	A semicolon-separated list of Product Variant SKUs to exclude for the assigned Product. Only these Variants are excluded. The Product's other Variants stay in the selection. Applies to `IndividualExclusion` mode.	Optional

Import multiple assignments for a Product Selection

To assign more than one Product to a Product Selection, list each assignment on its own row. Leave the parent-level columns (key, name, mode, and Custom Fields) empty in the additional rows. The import merges these rows into the Product Selection identified by the most recent non-empty key.

`key`	`name.en`	`mode`	`assignments.product.key`
`summer-collection`	`Summer collection`	`Individual`	`pillow-cover`
			`beach-towel`

List update behavior

For Product Selections, you can set Merge or Replace for the Assignments list field.

For more information, see List update behavior.

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 clear the localized name for the German locale on a Product Selection, add a column for name.de with [DELETE] as its value.

`key`	`name.en`	`name.de`
`summer-collection`	`Summer collection`	`[DELETE]`

Prerequisites.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Supported headers and values.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Product Selections.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Custom Fields.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Sets of Custom Fields.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Sets of complex Custom Fields.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Product assignments.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Import multiple assignments for a Product Selection.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

List update behavior.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Delete data.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}