File Format - Variant
Variant File Format
The first line of a Variant CSV file must be the header row.
A variant instance is a group of rows in the CSV file that are sequential and include the same required fields. Data relating to fields specified under Base Headers and Multi-Column Headers must be specified in the first row of a variant instance. Additional rows of a variant instance may only include fields specified under Multi-Row Headers.
Required Headers
To successfully import a variant CSV file, the following columns must be included in the header row:
| Column Name | Description | Type |
|---|---|---|
Variant ID(Required) | Identification string for a variant. Must be unique for each product, otherwise overwritten. | string |
Product ID | ID of the product this is a variant of | string |
UPC | UPC of the variant | string |
Status (Required) | Status of the variant. 0 = active, 1 = disabled, 2 = unavailable | integer |
Sort Order | Sort order of the variant | integer |
| Groups | May Be Required | See below |
Groups
A group is a class of headers that relate to one another, and may allow for multiple pieces of information to be presented. For example, a customer can have multiple emails, addresses, phone numbers, and more.
Variant groups include:
- Images (Recommended)
- Localized Data (Required)
- Option Values (Required)
- Identifiers (Optional)
- Related Variants (Optional)
Images (Recommended)
There are two ways that images can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one column header is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, one column header may be used many times alongside one row (the first row) of a variant instance. To use this column multiple times, an identifying number must exist for N and be unique for each new column.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Images group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Image | Image N | URL to images of the variant. | string |
Where N is some positive integer.
Localized Data (Required)
There are two ways that localized data can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of a variant instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Localized Data group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Localized Description(Required)* | Localized Description N | Description of the variant localized to the specified language | string |
Localized Language ID(Required)* | Localized Language ID N | ID of the language in which the record appears. Integers will be resolved to internal identifiers | integer, string |
Localized Name(Required)* | Localized Name N | Name of the variant localized to the specified language | string |
Where N is some positive integer.
Note:
(Required)*means these fields are required when sending
Option Values (Required)
There are two ways that option values can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one column header is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, one column header may be used many times alongside one row (the first row) of a variant instance. To use this column multiple times, an identifying number must exist for N and be unique for each new column.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Option Values group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Option Value ID (Required) | Option Value N ID | ID of an Option Value associated with the variant | string |
Where N is some positive integer.
Identifiers (Optional)
There are two ways that variant identifiers can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of a variant instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Related Variants group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Identifiers Identifier | Identifiers N Identifier | The code for the additional identifier of the variant | string |
Identifiers Type | Identifiers N Type | Variant identifier type, e.g. upc | string |
Where N is some positive integer.
The valid identifier types are:
- upc
- ean
- code93
- gs1
- code128
- other
Where “other” is the default type.
Related Variants (Optional)
There are two ways that related variants can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of a variant instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Related Variants group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Related Variant ID | Related Variant N ID | ID of the related variant | string |
Related Variant Sort Order | Related Variant N Sort Order | Sort order of the related variant within its set of related variants | integer |
Where N is some positive integer.
Custom Attributes
There are two ways that custom attributes can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of a variant instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Custom Attributes group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Custom Attribute ID | Custom Attribute N ID | Identifier of the custom attribute | string |
Custom Attribute Value | Custom Attribute N Value | Value of the attribute | string |
Custom Attribute Language ID | Custom Attribute N Language ID | Language of the attribute. Supported languages and their ids can be found here Integers will be resolved to internal identifiers | integer, string |
Where N is some positive integer.
Variant CSV Example
See the following Variant CSV sample file.