Documentation

Import data

Elevate, May 20-22-2025, Miami Beach, Florida

Learn how to create and update resources by importing data.

You must import Custom Object data from JSON files. You import data for all other resources from CSV files.

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, Inventory, and Custom Objects
  • View and edit all: Product types permission for importing Product Types
  • View and edit all: Discount codes permission for importing Discount Codes

Identifiers

Import and export functionality uses only user-defined identifiers, such as keys, to identify resources.

System-generated ID values are unique within a single Project. This makes them unsuitable for managing data across multiple Projects (such as staging and production). In these scenarios, resource ID values will differ between Projects, whereas user-defined identifiers can be maintained consistently. Relying solely on user-defined identifiers therefore ensures predictable and reliable data imports across different Projects.

The importer performs an "upsert" operation: it updates a resource if its specified key exists, or creates a new resource with that key if it doesn't. Therefore, you must provide keys for each resource you import, including embedded objects such as Product Variants, Prices, and Assets. This means you cannot use the importer to assign key values to existing resources or embedded objects that don't have one, or to change their current key.

Creating a new resource may still fail if a field value conflicts with an existing value stored in a particular resource causing a duplicate.

Add keys to existing resources and objects

Keys are optional, so they may be missing from your Project's resources and embedded objects. If your existing resources and embedded objects don't have keys (for example, because you previously used ImpEx for imports), we recommend the following options for adding them.

Even if your business cases do not require keys, you must add them to your existing resources and objects before you can use the Merchant Center for importing updates.

If you don't have keys on the resources and objects before your first Merchant Center import, the process will create new resources and objects instead of updating the existing ones.

Use the API

If you want to develop an application that sets keys for your resources, use the respective update actions on our APIs. For example,

Use our command-line tool

If you do not require a specific key format and you have Node.js installed on your computer, you can use our key-applier tool.

This tool automatically adds keys to your existing Cart Discounts, Categories, Customers, Customer Groups, Discount Codes, Products, Standalone Prices, and Tax Categories.

The added keys will have the format {resourceType}_{resourceId}., for example, a Category will get a key like: category_512a4466-6876-4c41-add8-1406c6c68da3.

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, Products, and Product Types. Include only the headers and values for the fields that you are updating.
When importing Custom Objects, the value field should include all existing values and not just the values you are updating.
We provide template files that show how to structure import files for each resource. CSV files previously used with ImpEx have a different structure and cannot be used.

Importing an CSV file exported with filled rows

If you have exported data with Fill all rows with complete data selected, you must ensure that any changes made to repeated data is replicated on every row. Failure to do so may result in import errors, or incorrect resources being imported.

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 template

The following template files show how to import data from JSON (Custom Objects only) and 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 an import file

  1. Go to Operations > Import, and click the Upload files tab.
  2. Select the data 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 or JSON 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.