Run bulk operations and import/export jobs
Run bulk operations and import/export jobs
Choose the data mechanism that fits your operation rather than sending one unbounded request. Cursor reads, bulk mutations, and asynchronous jobs have different success and recovery contracts.
Choose a mechanism
| Need | Use |
|---|---|
| Read another page in an interface | Cursor pagination |
| Write several supported resources in one request | A documented bulk mutation |
| Import or export a supported file format | The corresponding asynchronous job |
A bulk mutation is not automatically a job, and an error list is not automatically a partial-success contract.
Run a bounded batch
Keep inputs within the operation’s documented maximum. Common catalog bulk operations accept up to 100 entries; check the exact field before choosing a batch size. Retain a ledger of source keys and the intended inputs, and select both result resources and business errors.
inventoryEntryBulkCreate is transactional. Correct a rejected batch before resubmitting it. Verify each other operation’s contract independently rather than applying one blanket retry rule to all bulk fields.
After a successful response, persist the resulting IDs and source checkpoint together in your integration workflow. After an ambiguous response, read the affected records before retrying creation.
Start and follow a job
Product and translation file workflows expose job-starting mutations and job queries. Use the required Admin user authentication for job operations that require a user session. A service API key is not interchangeable with a user session for those operations.
- Check the specific import format, required columns, and operation inputs.
- Start the job and retain its ID.
- Poll the corresponding job query with bounded backoff.
- Wait for a documented terminal state.
- Inspect errors and output details before declaring the import or export complete.
See productsExport, translationsExport, and translationsImport. An upload scalar requires a multipart-capable client; placing a base64 string in JSON does not create a file upload.
Verify the destination
Sample records across batch boundaries and compare identities, not just counts. For imported catalog data, check the Storefront view after publication. For exports, handle output files according to your retention policy and keep private customer or operational data out of public artifacts.
Use Catalog synchronization for ownership and reconciliation.