Run bulk operations and import/export jobs

Outcome: choose the correct large-data mechanism, preserve a checkpoint, and verify completion without assuming partial success or exactly-once delivery.

Prerequisites: an Admin credential, a stable source identifier, a bounded batch plan, and an error/reconciliation store. Product and translation jobs require a human Admin bearer token.

Cursor pagination

Connection queries return nodes or edges plus pageInfo. Request at most 100 records per page. Continue with after: endCursor until hasNextPage is false.

Do not derive cursors, reuse a cursor with a different filter or sort, or launch every page concurrently. A cursor belongs to the exact query shape that returned it.

For a long-running mirror, use a stable sort and persist both the cursor and the source checkpoint. If the data can change while paging, make the destination upsert idempotent and schedule a reconciliation pass.

Bulk mutations

Bulk create, update, and delete operations reduce network overhead but are not an unlimited transaction boundary. Inputs are capped at 100 entries.

• Split data into batches of 100 or fewer.
• Preserve a stable external key such as SKU in your own batch ledger.
• Request all returned resources and errors.
• Read the operation’s typed error as the outcome for the submitted batch.
• Do not turn an error list into a general partial-success contract.

Examples include productVariantsBulkCreate, productVariantPricesBulkCreate, inventoryEntryBulkCreate, and translationsUpsertBulk.

inventoryEntryBulkCreate validates conflicts and duplicates for the batch, stages the entries, and saves once. On a reported failure, correct the batch and replay it as a batch. Verify every other bulk mutation independently before choosing whole-batch or item recovery.

Imports and exports

Product and translation imports and exports run asynchronously:

These job-starting mutations require a human Admin user. Authenticate with Authorization: Bearer {{token}}; an API key does not contain the user ID and email claims needed to create and deliver these jobs.

1. Start the mutation and retain the returned job ID.
2. Poll the corresponding job query with backoff.
3. Wait for a terminal state.
4. Inspect job errors even when the job produced an output file.
5. Download export files promptly and store them according to your data-retention policy.

productsExport can export products, variants, or variant prices by selecting the appropriate level. Translation jobs can be limited to selected entity types and locales.

Uploads use the GraphQL multipart request specification. Send the Upload value through a multipart-capable GraphQL client; a base64 string inside JSON is not equivalent.

Verify

After a bulk response, query a sample from the start and end of the batch. After a job reaches its terminal state, inspect job errors and output metadata before advancing the source checkpoint. Run a periodic count and identity reconciliation even when every request returned successfully.