Documentation

Import data

Learn how to create and update resources by uploading data from a CSV file.

Prerequisites and preparation

Permissions

To import data, the Administrators Team must grant you the following permissions for the Project:

  • View all: Operations permission for accessing Import Logs
  • View and edit all: Operations permission for importing resources through CSV files
  • View and edit all: Categories permission for importing Categories
  • View and edit all: Products permission for importing Products and Inventory
  • View and edit all: Discount codes permission for importing Discount Codes

Use keys as identifiers

Keys are required to import data. You must include keys for every resource you import, including embedded objects such as Product Variants, Prices, and Assets.

If a resource or embedded object with a specified key exists when importing data, it is updated with the given values. If a resource or embedded object with the specified key does not exist, a new one is created.

You can update a resource only if it has a key. We recommend setting keys for your resources and objects by using the Set Product Key, Set ProductVariant Key, Set Price Key, and other "Set Key" update actions on the HTTP API.

Use the correct data structure

CSV files must have a specific data structure with defined headers and values. You can view these headers and values in Categories, Discount Codes, Inventory, and Products. Include only the headers and values for the fields that you are updating.

We provide CSV templates that show how to structure CSV files for each resource. CSV files used with ImpEx have a different structure and cannot be used.

Limits of CSV files

The CSV file that you want to upload must be no larger than 35 MB and contain fewer than 80 000 rows. If your CSV file exceeds these limits, split the content into multiple files.

Download a CSV template

The following CSV templates show how to import data from CSV files. These templates are compatible with our B2C sample data, and they can help you understand how to create templates with your own data.

As Product data can be complex, you can import a single file containing the complete product data or smaller files for only updating assets, images, pricing, and price tiers.

Upload a CSV file

  1. Go to Operations > Import, and click the Upload files tab.

  2. Select the resource type from the drop-down, upload the file, and then click Upload and preview.

    When importing Products, select the Publish all products in the file checkbox to update the current and staged representation of existing Products, and publish new Products. If not selected, the imported data will only update the staged representation of existing Products and new Products created by the import process are not published.

    Preview of a Categories import after file upload.

  3. After the file is uploaded and validated successfully, verify the information, and then click Start import. You can also upload another file simultaneously while an import operation is running.
    To monitor the import progress, click the Import logs tab. For more information, see Import logs.

Import logs

Import logs are historical records of all your import activities performed in the last 48 hours using the Merchant Center or Import API. It helps you track the import progress, and check errors and pending actions in Import Containers.

To access the import logs, go to Operations > Import. The import logs table is generated when the page is loaded. To update the visible data thereafter, click the refresh button.

The import log table has the following columns:

  • Time created: date and time the import container was created.
  • Import container key / File name: name or unique key of the import container.
  • Import type: indicates the method of data import:
    • Automated import: imported using the Import API.
    • Manual file upload: imported from a CSV file.
  • Resource type: resource type provided at the time of the import container creation.
  • Status: import status of an import container:
    • Successfully completed: all resources were successfully imported.
    • Partially completed: some import operations were successful while others are in Failed or Unresolved states.
    • Failed: all import operations were unsuccessful.
    • Processing: some import operations are still in progress.
    • Wait for unresolved references: some import operations are Unresolved and are awaiting missing or undefined references.
    • Canceled: the import operations were manually terminated. Resources imported before cancellation were not removed.
    • No running imports: the import container has no running or waiting import operations.

History of an Import Container

To view individual import request items or operations of an Import Container, click the corresponding row in the import logs table. The operations are uniquely identified by resource key and the table displays the following details:

  • Status: symbolic representation of an import operation's status:
    • Red indicates a Failed operation.
    • Blue indicates an operation in progress or waiting.
    • Green indicates a Successful operation.
  • Identifier: unique identifier of an operation.
  • Validation message: placeholder for the details of the import status that displays the detailed error, required action, or success message.