CSV imports and exports

Every import Store Admin offers, with its modes (the first is the default), options, the scopes it needs to run (write_scopes) and read (read_scopes), and whether it can be cancelled or undone. partial imports apply the valid rows and skip rows with errors; the others need an error-free file. A translation import also needs its resource's owner scope (for example write_products for product).

Step 1 of an import. Send the import type and one item describing the file; the response carries an intent with an upload URL. PUT the file there, then finalize the intent. The file's size, row and column limits are the type's Store Admin limits, checked at upload. The token needs the scopes of the request's type (see GET /imports/types and GET /exports/types); a missing one returns 403 CSV_JOB_SCOPE_REQUIRED naming it.

Step 2: after the PUT, finalize the intent with the same type. The intent keeps the resource given at the create step, so a translation upload is not told it again. The file is checked (CSV, size, row and column counts); poll the status endpoint until the intent is ready, then pass its file_id to POST /imports.

Returns the intent's state; once it is ready, its file_id creates the import.

Step 3. Runs the same analysis as the Store Admin import wizard and returns the import in preview: row counts (creates, updates, unchanged, skips, errors), file warnings such as ignored columns, and can_confirm. Nothing is written until POST /imports/{importId}/confirm. Read row errors with GET /imports/{importId}/errors. The preview expires after 24 hours (expires_at). status is ready when the import can be confirmed and blocked when the file's errors stop it (fix the rows, upload the file again and create a new import). A large file can take up to 25 seconds to analyze; a busy service returns 503 and the request can be repeated with the same Idempotency-Key. The token needs the scopes of the request's type (see GET /imports/types and GET /exports/types); a missing one returns 403 CSV_JOB_SCOPE_REQUIRED naming it.

Imports created through the Store API or a connected tool whose type this token can read, newest first. Paged by cursor. Each import and export carries status_display and type_display, its status and type as shown in Tringify (type_display is the type's label from the types list), in English; an import's job carries status_display too.

Before confirmation status is ready, blocked or expired, and confirming while the job is being started. After it, status is the job's: validating, processing, completed, failed or cancelled, and job carries progress and result counts (processed_rows, succeeded, failed, skipped). An attributes import counts attributes in total_rows and processed_rows (a file row is one option of an attribute) and reports the file's option rows in job.option_rows (total, processed); other import types omit it. Poll until completed, failed or cancelled. Each import and export carries status_display and type_display, its status and type as shown in Tringify (type_display is the type's label from the types list), in English; an import's job carries status_display too.

Before confirmation these are the preview's row errors; after it, the rows the job could not apply. Each error names the CSV row, the field when known, a code and a message. A job keeps its first row_error_limit row errors; total counts them all.

Starts the job for the previewed file, exactly as Start import in Store Admin, and returns the import with status validating or processing. Confirm only after reviewing the preview counts and errors with the merchant. Repeating it returns CSV_IMPORT_ALREADY_CONFIRMED. The token needs the scopes of the request's type (see GET /imports/types and GET /exports/types); a missing one returns 403 CSV_JOB_SCOPE_REQUIRED naming it.

Deletes the preview without changing anything, like Discard in the Store Admin wizard. A store keeps one active preview per type for reviews, tags, historical orders, sales baselines and tax rates, so discard an unwanted one before creating another. The token needs the scopes of the request's type (see GET /imports/types and GET /exports/types); a missing one returns 403 CSV_JOB_SCOPE_REQUIRED naming it.

Cancels a confirmed import that hasn't finished, like Cancel in Store Admin's bulk jobs. Rows already applied stay applied. Translation imports can't be cancelled. The token needs the scopes of the request's type (see GET /imports/types and GET /exports/types); a missing one returns 403 CSV_JOB_SCOPE_REQUIRED naming it.

Historical order imports only, with the same rules as Undo import in Store Admin: orders that have since changed (paid, fulfilled, refunded, edited) are kept and counted in blocked. The first call returns 409 CONFIRMATION_REQUIRED with the impact (orders_in_batch, deletable, blocked) and a single-use confirmation_token; show it to the merchant and repeat the call with confirmed: true and the token. One call deletes a bounded batch; while remaining is above 0, repeat the confirmation round. The token needs the scopes of the request's type (see GET /imports/types and GET /exports/types); a missing one returns 403 CSV_JOB_SCOPE_REQUIRED naming it.

Every export Store Admin offers, with its options (filters) and the scopes it needs. A translation export also needs its resource's owner read scope.

Starts the same export as Store Admin's Export button and returns it with status processing. Poll GET /exports/{exportId}; when status is completed it carries a short-lived download_url. The file uses the import columns, so an edited export can be imported again (for translations: export, translate the file, then import it with the same resource and locale). A Gift Cards export is a listing only: its import issues new cards and cannot update existing ones. The token needs the scopes of the request's type (see GET /imports/types and GET /exports/types); a missing one returns 403 CSV_JOB_SCOPE_REQUIRED naming it.

Exports created through the Store API or a connected tool whose type this token can read, newest first. Paged by cursor. A download_url is only on GET /exports/{exportId}. Each import and export carries status_display and type_display, its status and type as shown in Tringify (type_display is the type's label from the types list), in English; an import's job carries status_display too.

status is processing, completed, failed or cancelled. A completed export has download_url, a signed link valid for 5 minutes (download_expires_at); read the export again for a fresh link. Each import and export carries status_display and type_display, its status and type as shown in Tringify (type_display is the type's label from the types list), in English; an import's job carries status_display too.

Cancels an export that hasn't finished. Newsletter subscriber and translation exports can't be cancelled.