Skip to main content

Product Import/Bulk Update

You can use Product Import to:

  • Add new products. For new products that you want to add, the entry in the .csv file must have an external_ref that does not match any existing products.

  • Add new:

  • Update existing products, including images, templates/flow fields and entries. The entry in the .csv file must have a unique id and/or external_ref that matches the id and external_ref of the existing product you want to update. You may have both a unique id and external_ref, but you must have at least one.

You cannot use product import to:

  • Delete existing products.
  • Import product bundles.

Product Import uses a Comma Separated Values (CSV) file to import/update products, main image files, and custom extension data. See an example file.

When you send a product import request, a job is created. Jobs are processed one at a time. You can continue to send product import requests, but those jobs are queued. In other words, Commerce looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. See Jobs API or Jobs in Commerce Manager.

We recommend that you include the maximum allowed number of products in each csvfile (for example, up to 50,000 rows or a file size of 50 megabytes, see Comma Separated Values (CSV)) to minimize the number of files you submit. This helps prevent extended waiting times for processing jobs.

Using Imported Main Image Files​

You can use the main images that you have previously uploaded to Commerce and assign them to your products when importing products to Commerce. You can do this by adding a main_image_id header to your .csv file. The ID you provide in main_image_id is the ID of a file that has already been uploaded to Commerce using create a file.

Importing Custom Data (Flows)​

You can also create/update custom extension data in a .csv file by creating a header that includes the flow ID and the field slug in the following format:

template:flowID:fieldSlug.

where:

  • template must be template.
  • flowID is the ID of the flow that contains the field whose data you want to create/update.
  • fieldSlug is the slug of the field whose data you want to create/update.

In the following example, for a flow with ID 82c10a02-1851-4992-8ecb-d44f2782d09b and a field with the slug condition:

  • the header is template:82c10a02-1851-4992-8ecb-d44f2782d09b:condition.

  • the updated custom data is as-new.

    nameslugskustatustemplate:82c10a02-1851-4992-8ecb-d44f2782d09b:condition
    BestEver Rangebestever-range-1a1a-30BE-Range-1a1a-30draftas-new

Characteristics of CSV Import Files​

Product Import uses a Comma Separated Values (CSV) file to import/update products, main image files, and custom extension data.

  • Each row in a .csv file represents a product you want to create/update.
  • Each file:
    • must not be larger than 50 megabytes. If a .csv file is larger than 50 megabytes, a 503 client read error is displayed.
    • must not have more than 50,000 rows, including the header. If a CSV file exceeds 50,000 rows, an error is displayed, and the products are not imported. In other words, if you have a file with 50,000 rows that is larger than 50 megabytes, an error is displayed, and the products are not imported.
  • If you want to create/update more than 50,000 products or your .csv file is larger than 50 megabytes, you must have a separate .csv file and import each .csv file one at a time.
  • You can update existing products, including images, templates/flow fields, and entries. The entry in the .csv file must have a unique id and/or external_ref that matches the id and external_ref of the existing product you want to update. You may have both a unique id and external_ref, but you must have at least one.
  • You can add new products. For new products that you want to add, the entry in the .csv file must have an external_ref that does not match any existing products.

The following table describes the headers that are supported.

HeaderRequiredDescription
idOptionalA unique product ID that is generated when you create the product. The id is used to look up products in the .csv file and matches them to the products in your storefront that you want to update.
external_refOptionalA unique attribute associated with a product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.
nameRequiredThe name of a product.
descriptionRequiredA description for a product. You can include quotes in your product description, if you want to emphasize a word, for example. To do this, put quotes around the product description. For example, "This product description describes my "product" and the product "version"."
slugRequiredA label for the product that is used in the URL paths. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. NO spaces or other characters are allowed. By default, the product name is used as the slug.
statusRequiredThe status of a product, either Draft or Live.
commodity_typeRequiredThe commodity type, either physical or digital.
upc_eanOptionalThe universal product code or european article number of the product.
mpnOptionalThe manufacturer part number of a product.
skuOptionalThe unique stock keeping unit of the product.
tagsOptionalThe product tags used to store or assign a key word against a product. A product can have up to 20 product tags. A product tag can be up to 255 characters. See Product Tags.
main_image_idOptionalSpecifies a unique ID of a main image file for a product. You can include a main_image_id for your products for images that are already uploaded to Commerce. See Using Main Image Files.
template:<flowID>:<fieldSlug>OptionalYou can also specify custom extension data in the CSV by specifying the flow ID or slug and the field name. For example, template:<flowSlug>:<fieldName> format. See Importing Custom Data (Flows).