Starting from version 2026-04, DraftOrderLineItem to components a field has been added. Component items hanging off a parent line item (bundle contents, etc.) can now be retrieved as-is in a parent-child nested structure.
flattenComponents has been added.
Parent and components were returned side by side as line items in a single flat list. From the response structure alone, you couldn't tell which was the parent and which were its contents.
Only parent line items appear at the top level, and components hang under the components field. The parent-child relationship is reflected directly in the structure.
DraftOrderLineItem.components is a field that returns
the individual component line itemstied to that line item.
For cases like bundle products where "a single parent item is composed of multiple contents,"
the contents can be expressed nested under the parent.
name and quantity are used.
DraftOrder.lineItems An optional argument added to the connection,
flattenComponents , switches how component items are returned.
The top-level nodes contains only parent line items. Components are traversed via each parent's components .
Both parents and components are returned as sibling nodes entries. Same behavior as versions before 2026-04.
| API version | Default for flattenComponents | Return shape |
|---|---|---|
| 2026-04 and later | false | Top level contains only parent line items; components are retrieved from DraftOrderLineItem.components |
| Before 2026-04 | true | Both parents and components are returned as top-level nodes (for backward compatibility) |
flattenComponents: true explicitly, orcomponents migrate to an implementation that traverses it.Example from the article. It retrieves the parent line item's components as nested fields (assuming the default false ).
query { draftOrder(id: "gid://shopify/DraftOrder/1") { lineItems(first: 10) { nodes { name quantity components { name quantity } } } } }
nodes Inside each element (parent) of , components just write it nested. If you want the flat legacy behavior, pass an argument like lineItems(first: 10, flattenComponents: true) .This change is about Customer Account API . It applies to contexts where "the customer themselves accesses the page," such as My Page, allowing components of draft orders to be visible. Treat it as separate from the equivalent change in the Admin API.
In 2026-04, flattenComponents becomes false by default. When you bump the version, the contents of nodes change to "parents only." This is the most critical checkpoint when upgrading.
If you can't rush the migration, explicitly setting flattenComponents: true will return parents and components flat side by side just like before, even on 2026-04. It serves as an escape hatch for phased migration.
Under the default behavior, components cannot be retrieved unless you add DraftOrderLineItem.components to your query. Aggregation logic that assumes a flat structure must be rewritten as a two-tier loop: parent loop → child loop.
The full type of the component line item, the complete set of retrievable fields, behavior during pagination, and consistency with other APIs (Admin / Storefront) arenot described in this article. If you use anything beyond what appears in the sample name / quantity , verify against the actual version's schema.
components as an indented child list.components loop, rendered in two tiers.name / quantity are fields verified in the article's sample.flattenComponents: true explicitly to bump just the API version first, → ② thencomponents gradually migrate to a nested implementation that walks .components as 'breakdown rows,' preserving the hierarchy when exporting to PDFs / business documents.true), nested for display (false) — using flattenComponents for the right purpose keeps the logic clean.components A new field plus theflattenComponents argument lets you switch back to the legacy flat behavior.