File Format - Product
Product File Format
The first line of a Product CSV file must be the header row.
A product 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 product instance. Additional rows of a product instance may only include fields specified under Multi-Row Headers.
Spec
The following table shows the accepted CSV columns for the products entity. Note that any columns including N denote a dynamic integer. A column specified as Field N signifies that you can use columns Field 1, Field 2, …, Field N to allow for multiple values per record of the given field, similar to an array.
| CSV Header | Data Type | Group | Required | Description |
|---|---|---|---|---|
Product ID | string | Yes | External identifier of the record | |
Category | string | Categories | No | Array of Category IDs representing the Categories to which this Product belongs (externalId resolvable) |
Category N | string | Categories N | No | Array of Category IDs representing the Categories to which this Product belongs (externalId resolvable) |
Model | string | No | Model of the Product | |
Status | integer | No | Product Status defaults: 0 = Disabled, 1 = Active, 2 = Sold Out, 5 = Coming Soon. See integration specification for instance-specific usage of this field | |
Tax ID | integer | No | ID of the Tax to be used with the Product | |
Tax Code | string | No | ||
Tax Class Code | string | No | ||
UPC | string | No | UPC of the Product | |
Weight | number | No | Weight of the Product (decimal precision: float) | |
Width | number | No | Width of the Product (decimal precision: float) | |
Custom Attribute ID | string | Attribute Values | No | Attribute to be used as key in the key/value pair (externalId resolvable) |
Custom Attribute Language ID | integerORstring | Attribute Values | No | Language ID for the language in which this value appears; use 0 if it is not localized (externalId resolvable) |
Custom Attribute Value | string | Attribute Values | No | Value to appear in this key/value pair |
Custom Attribute N ID | string | Attribute Values N | No | |
Custom Attribute N Language ID | integerORstring | Attribute Values N | No | |
Custom Attribute N Value | string | Attribute Values N | No | |
Localized Description | string | Localized Data | No | Description of the Product localized to the language in languageId |
Localized Language ID | integerORstring | Localized Data | No | ID of the Language in which the record appears (externalId resolvable) |
Localized Name | string | Localized Data | No | Name of the Product localized to the language in languageId |
Localized Subtitle | string | Localized Data | No | Subtitle of the Product localized to the language in languageId |
Localized URL | string | Localized Data | No | URL of the Product localized to the language in languageId |
Localized Description N | string | Localized Data N | No | Description of the Product localized to the language in languageId |
Localized Language ID N | integerORstring | Localized Data N | No | ID of the Language in which the record appears (externalId resolvable) |
Localized Name N | string | Localized Data N | No | Name of the Product localized to the language in languageId |
Localized Subtitle N | string | Localized Data N | No | Subtitle of the Product localized to the language in languageId |
Localized URL N | string | Localized Data N | No | URL of the Product localized to the language in languageId |
Image | string | Images | No | Array of URLs of images of the Product |
Image N | string | Images N | No | Array of URLs of images of the Product |
Video | string | Videos | No | Array of URLs of videos of the Product |
Video N | string | Videos N | No | Array of URLs of videos of the Product |
SortOrderOverrides OptionValueID | string | OV Overrides | No | |
SortOrderOverrides Sort Order | integer | OV Overrides | No | |
SortOrderOverrides N OptionValueID | string | OV Overrides N | No | |
SortOrderOverrides N Sort Order | integer | OV Overrides N | No | |
Related Product ID | string | Related Products | No | The Product External ID of the related product. This field is returned as null in GET operations as it isn’t ID resolvable. |
Related Product Sort Order | integer | Related Products | No | The sort order for the Related Product within its set of related products |
Related Product N ID | string | Related Products N | No | |
Related Product N Sort Order | integer | Related Products N | No | |
Catalog | integerORstring | Catalogs | No | |
Catalog N | integerORstring | Catalogs N | No | Array of catalog IDs of Product (externalId resolvable) |
Track Inventory | boolean | No | ||
Default Variant ID | integer | No |
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.
Images (Recommended)
Note: The following file extensions are supported
.jpg,.JPG,.jpeg,.JPEG,.png,.PNG,.gif,.GIFfor product images.
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 product 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:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| No | Image | Image *N* | URL to an image of the product | string |
Where N is some positive integer.
Videos (Optional)
There are two ways that videos 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 product 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 Videos group.
The following columns may be included:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| No | Video | Video N | URL to a video of the product | string |
Where N is some positive integer.
Localized Data (Optional)
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 product 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:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| No | Localized Description | Localized Description N | Description of the product localized to the specified language. This can include HTML and CSS. | string |
| Yes | Localized Language ID | Localized Language ID N | ID of the language in which the record appears. Supported Languages and their IDs can be found here. Integers will be resolved to internal identifiers | integer, string |
| Yes | Localized Name | Localized Name N | Name of the product localized to the specified language | string |
| No | Localized Subtitle | Localized Subtitle N | Subtitle of the product localized to the specified language | string |
| Yes | Localized URL | Localized URL N | URL of the product localized to the specified language | string |
Where N is some positive integer.
Option Value Overrides (Optional)
There are two ways that option value overrides 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 product 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 Option Value Overrides group.
The following columns may be included:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| No | SortOrderOverrides OptionValueID | SortOrderOverrides N OptionValueID | ID of the Option Value. Integers will be resolved to internal identifiers | integer, string |
| No | SortOrderOverrides Sort Order | SortOrderOverrides N Sort Order | Sort order for the Option Value | integer |
Where N is some positive integer
Related Products (Optional)
There are two ways that related products 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 product 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 Products group.
The following columns may be included:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| No | Related Product ID | Related Product N ID | ID of the related product | string |
| No | Related Product Sort Order | Related Product N Sort Order | Sort order for the related product within its set of related products | 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 product 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:
The following columns may be included:
| Required | Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|---|
| No | Custom Attribute ID | Custom Attribute N ID | Identifier of the custom attribute | string |
| No | Custom Attribute Value | Custom Attribute N Value | Value of the attribute | string |
| No | Custom Attribute Language ID | Custom Attribute N Language ID | Language of the attribute. Integers will be resolved to internal identifiers | integer, string |
Where N is some positive integer
Product CSV Example
See the following Product CSV sample file.