Export and import product data
Product data can be exported or imported from external systems.
Once you have set up products and SKUs, as described in Create and work with products and Create and work with SKUs, you can share the data.
Products are associated with Master View or standard catalogs or collections. For detailed information on the difference between these two types of catalogs, refer to Understand catalogs.
When you create a product the product is linked, by default, to the master
defaultCategoryForProducts
category. If you indicate that the
category is null, or you set the orphaned
attribute to
true
, the product you create is identified as orphaned. If you
provide a valid a standard catalog ID, the product is linked to the
defaultCategoryForProducts
category of the specific catalog.
Products cannot be linked to root categories of any catalog. If you provide root
categories in the parentCategories
attribute, the product is linked to
the defaultCategoryForProducts
of that specific catalog. However, if
you provide both parentCategories
and a catalogId
, the
catalogId
is ignored.
Note that the catalogId
and orphaned attributes are not exported, as these properties are used only when performing an import.
Product-specific export and import fields
The following sections describe the fields that can be exported and imported for products. Note that both the product and SKU data are imported into and exported to a single file. The product and SKU fields have been separated in the following tables for the sake of clarity.
Product import issues
If you import a large number of products, you could experience some performance issues if the products are not categorized properly. To avoid these issues, consider the following:
- A collection should not hold too many products.
- Avoid creating too many products without any category.
- Avoid creating too many price groups.
Field Type | Description |
---|---|
Product price information |
Fields that contain pricing information, such as You can upload pricing information into multiple price list groups. |
Tax information | The tax code of the product. |
Product Add-Ons |
Add-on product associated with the product with the property
Add-Ons are not supported at SKU level. Only at product level. |
Product description information | Fields that describe the product, such as height ,
weight , length ,
brand , type and
displayName .
|
Product image information | The product image description field productImages that contains
path , metadata ,
repositoryId , name ,
url and tags . Also describes
additional information about images, such as
productImagesMetadata ,
primaryImageTitle and
primaryImageAltText . Note that you cannot
import images along with the corresponding product. However, you can
map images that you have already uploaded to the products that you
are importing. To do this, refer to the Import image
assignments.
|
Additional product information | Fields that contain information such as unitOfMeasure , onlineOnly , configurable , discountable , orderable , active , notForIndividualSale , orderLimit , variantValuesOrder and CountryOfOrigin .
|
Associated SKU descriptions | Fields that contain descriptions about associated SKUs, such as
childSKUs and
defaultProductListingSku .
|
Additional related product fields | Fields that contain additional product and related fields descriptions, such as
description , longDescription ,
relatedProducts ,
relatedArticles and
relatedMediaContent .
|
Date and time | Fields that provide dates and times, such as
salePriceStartDate ,
salePriceEndDate ,
creationDate , arrivalDate ,
dateAvailable and
daysAvailable .
|
Linking information | Fields that provide information on linking fields. For example,
parentCategories . Note that
parentCategories is imported first and during
product import, it is linked to the corresponding parent categories
using its repositoryId .
|
SKU-specific export and import fields
The following fields can be exported and imported for SKUs.
Field Type | Description |
---|---|
SKU price information | Fields that contain pricing information, such as listPrice ,
listVolumePrice , listPrices ,
listVolumePrices , salePrice ,
saleVolumePrice , salePrices ,
and saleVolumePrices .
|
SKU image information | The SKU image description field images that uses path ,
metadata , repositoryId ,
name , url and
tags . Note that you cannot import images along
with the corresponding SKU. However, you can map images that you
have already uploaded to the SKUs that you are importing. To do
this, refer to the Import image
assignments.
|
Product related information | Fields that describe related product data, such as
productFamily and
productLine .
|
Date and time | Fields that provide dates and times, such as
salePriceStartDate ,
salePriceEndDate ,
creationDate , arrivalDate ,
dateAvailable and
daysAvailable .
|
Boolean fields | Fields that describe SKU properties, such as active , discountable , and configurable .
|
Dynamic SKU information | Fields that contain information specific to dynamic SKUs, such as
color and resolution .
|
Product and SKU validations
The following list describes some of the validation performed when importing products:
- The product ID is valid and not null. Valid characters are alphanumeric, as well as underscore (_) and dash (-).
- The
listPrices
andsalePrices
properties are either maps or null. If it is a map, each price corresponding to a price group ID is either a number or null. - The
listVolumePrices
andsaleVolumePrices
properties are either a map or null. If it is a map, each price corresponding to a price group ID is either a map or null. - The
listPrices
andlistVolumePrices
properties cannot contain a non-null entry for a particular price list group ID i.e. a particular product or SKU cannot have both list and list volume prices for a particularpricelistgroup
. - The
salePrices
andsaleVolumePrices
properties cannot contain a non-null entry for a particular price list group ID i.e. a particular product or SKU cannot have both sale and sale volume prices for a particularpricelistgroup
. - The
listPrice
, which should be a positive number, should be available for the mandatory price list groups. - If a site not account-enabled, the
listPrice
of a product cannot be null. - The
listPrice
cannot be less than thesalePrice
. - The
shippingSurcharge
should be a positive number. - If
categoryId
is null thecategoryItem
property will not be set. - The
productImages
property tags should be null or a map and if not null, each of its elements should be an instance of map or string. - The
childSKUs.configurationMetadata.name
property must be a string and is a required. - The
propertychildSKUs.configurationMetadata.value
property must be a string and is optional.
The following validations are also performed when importing SKUs:
- The corresponding catalog and product IDs should be valid and not null.
- The active property should be Boolean or String.
- SKU properties cannot be null, and should be unique. Additionally, the SKU ID should be valid, and a SKU with the same ID cannot pre-exist in the repository.
- Inbound SKU data should have all of the mandatory variant properties.
SKUs can be bundled together to create a new SKU. SKU bundles have the following validation:
- A SKU cannot be deleted if it is part of a SKU bundle.
- You can only bundle one level of SKUs.
- A SKU cannot be a member of multiple bundles, and you cannot have bundles referenced within bundles.
- SKUs can only be a part of the same bundle once.
For detailed information on working with products and SKUs, refer to Create and work with SKUs .
Support for hierarchical price list groups
If you have set up price groups by using base price groups, this hierarchy is supported in bulk product import. Note that the following validations are not performed in bulk import for performance reasons:
- The validation that
salePrice
value is lesser than list price value is not performed when there is price hierarchy. The price list group for the sale and list prices are added and inherit the parent price list group. - The validation that
salePrice
is given but the list price is missing is not performed when there is price hierarchy. The price list group for the sale price is added and inherits the parent price list group.