Pagination, bulk operations, and sync jobs

Choose the mechanism based on the size and direction of the data movement: connections for reads, bulk mutations for bounded writes, and jobs for file-based imports or exports.

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.
  • Record item-level failures and retry only failed items after correcting the cause.
  • Do not assume HTTP 200 or a partially populated payload means every input succeeded.

Examples include productVariantsBulkCreate, productVariantPricesBulkCreate, inventoryEntryBulkCreate, and translationsUpsertBulk.

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.