Skip to content

Shopify Dude Fix

Shopify Bulk Export JSONL Lost Parent Grouping? Fix groupObjects Before Parsing

Shopify Admin GraphQL 2026-01 defaults bulk query groupObjects to false. Fix parent-child JSONL parsing without making large exports unnecessarily slow.

Quick answer: On API 2026-01 and later, bulkOperationRunQuery defaults groupObjects to false. If your parser expects children directly after their parent, either explicitly request groupObjects: true or rewrite the parser to join JSONL rows by __parentId. Don’t assume a successful export means the row order is unchanged.
On this page

Why the old export parser broke

Older bulk-query examples assumed grouped JSONL: product rows followed by their variant or metafield rows. Shopify changed the default on October 29, 2025 for API 2026-01 because grouping adds processing overhead and can increase timeouts. Flat output is faster, but code that attaches a child to the most recently seen parent can now silently associate records with the wrong product.

Choose explicit grouping or order-independent parsing

First inspect the GraphQL API version and the actual JSONL output, not just the completed operation status. For a small legacy integration that truly needs adjacent parent/child rows, pass groupObjects: true to bulkOperationRunQuery. For large feeds, prefer the default flat output and build a parent lookup keyed by Shopify GID, using __parentId on child records. If the export is too large to keep all parents in memory, use a disk-backed lookup or a staged two-pass process. Do not sort all JSONL blindly by title or SKU.

Minimal GraphQL change

mutation {
  bulkOperationRunQuery(
    query: """{ products { edges { node { id title variants { edges { node { id sku } } } } } } }"""
    groupObjects: true
  ) {
    bulkOperation { id status }
    userErrors { field message }
  }
}

This restores grouped output for a query on 2026-01, at the cost of additional work by Shopify. The nested query still needs to meet Shopify’s bulk-query connection and nesting limits. Do not add groupObjects to bulk mutation jobs: Shopify deprecated that argument there because mutation output has no parent-object grouping to preserve.

Make failure observable

Log the API version, operation ID, status, file size, total rows, parent count, child count and unresolved __parentId values. Treat orphaned children as a failed import rather than silently dropping them. Run a representative export before deploying a version bump; API changes can alter data shape even when the schema validates.

Common misunderstanding: The JSONL export isn’t corrupt merely because product and variant rows aren’t adjacent. The guarantee changed. Grouping is optional, and relying on file order without requesting it is the bug.

How to test this

  1. Export two products with several variants and metafields using the old and new API versions.
  2. On 2026-01, compare the default flat output with an explicit groupObjects: true export.
  3. Verify every child attaches to the correct parent by GID, regardless of row order.
  4. Test a large dataset and compare runtime and memory use; retain grouping only if necessary.
  5. Force an unknown parent ID and confirm the importer reports an error instead of misassigning it.