Imports

An Import bulk-loads catalog data from a file rather than one API call per record. Each import targets an import type - the kind of data being loaded, such as product, collections or suppliers - which defines the columns the file is expected to carry and the metadata it accepts.

An import is a job: the upload is synchronous, but processing is asynchronous. The job starts pending, moves to processing, then ends completed or failed, and its report gives the per-row result once processing is done.

The Import object

Property	Type	Required	Description
@context	string | object	-
@id	string	required
@type	string	required
createdAt	string | null	-
format	"csv" | "tsv" | "xlsx" | null	-
id	string	-
metadata	object	-
report	object | null	-	Per-row processing report. Null until the import has been processed.
Show report fields Property Type Required Description error string - Present only when the import failed systemically. errors object[] required Show errors fields Property Type Required Description line integer required messages string[] required failed integer required imported integer required reset object - Records deleted per table, present only when metadata[reset]=true. totalRows integer required
status	"pending" | "processing" | "completed" | "failed" | null	-
type	"collections" | "categories" | "attributes" | "suppliers" | "attribute_options" | "purchase_offer" | "sale_offer" | "metafield_value" | "product" | null	required
updatedAt	string | null	-

How it fits together

1. Pick the type. List import types to see the supported types and the metadata each accepts (such as the locale, or the XLSX sheetName).
2. Prepare the file. In the unstable version, download an example file for the type rather than guessing the column layout.
3. Upload it. Create an import with the file, its type and any metadata, as multipart/form-data.
4. Follow the job. Retrieve the import until its status is completed or failed, then read its report: totalRows, imported, failed, and the errors of each rejected line.

Start from an example

The example download is only available in the unstable version. It returns a ready-to-fill file for a given type, in csv (default) or xlsx, and serves two different needs through its mode:

• sample (default) - a small, hand-crafted illustrative file showing the expected columns and a few example rows. Useful to discover the format.
• data - a full, re-importable export of your existing tenant data for that type. Useful to bulk-edit what you already have and load it back.

The two modes differ in what they require: sample needs only imports:read, while data also needs the read permissions of the target domain - for the product type, products:read or products:org:read plus medias:read.

Conventions

Authentication and headers

All requests require an OAuth 2.0 bearer token:

Authorization: Bearer <token>

Reading imports requires the imports:read scope; creating one also requires imports:write.