Draft Order の「構成品」が Customer Account API で取れるようになった

The HTML is ready, but the write to `site/public/raw/` needs your approval (the permission prompt was declined). Here's the complete document — intended filename `260401_line-item-components-draft-orders-customer-account-api.html` (matching the `urlToSlug` convention in `ingest.mjs`). If you'd like me to write it to disk, re-run with approval. Otherwise here is the full HTML: ```html 図解 ： Customer Account API で Draft Order の構成品（components）が取得可能に Customer Account API / 2026-04 Draft Order の「構成品」が Customer Account API で取れるようになった バージョン 2026-04 から DraftOrderLineItem に components フィールドが追加。親 line item にぶら下がる構成要素（バンドルの中身など）を、親子のネスト構造でそのまま取得できる。 このページの構成 そもそも何が変わるのか（30秒で理解） components フィールドとは ： 親子の関係を図解 flattenComponents ： 2 つの返り方を比較 API バージョン別のデフォルト挙動 サンプルクエリ（GraphQL） 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何が変わるのか Customer Account API の 2026-04 版で、Draft Order（下書き注文）の line item から 構成品（component line items）を親子構造で取得 できるようになった。 あわせて、構成品を「フラットに並べる／ネストにまとめる」を切り替える引数 flattenComponents が追加された。 従来 ： すべてフラット 親も構成品も、同列の line item として一列に並んで返ってきた。「どれが親で、どれが中身か」はレスポンスの構造からは読み取れない。 2026-04 ： 親子ネスト トップレベルには親 line item だけが並び、構成品は components フィールドの中にぶら下がる。親子関係がそのまま構造に表れる。 2 components フィールドとは ： 親子の関係を図解 DraftOrderLineItem.components は、その line item に紐づく 個々の構成 line item（component line items） を返すフィールド。 バンドル商品のように「1 つの親アイテムが複数の中身で構成される」ケースで、 中身を親の下にネストして表現できる。 記事が示すのは「親 line item に紐づく component line items を返す」という関係。 各構成品が具体的にどのオブジェクト型か・どんなフィールドを持つかの詳細はこの記事には記載なし 。サンプルでは name と quantity が使われている。 3 flattenComponents ： 2 つの返り方を比較 DraftOrder.lineItems 接続に追加された任意引数 flattenComponents で、構成品の返り方を切り替える。 flattenComponents: false 親子ネスト（2026-04 の既定） トップレベルの nodes は親 line item のみ。構成品は各親の components から辿る。 flattenComponents: true フラット（従来互換） 親も構成品も、すべて同列の nodes として返る。2026-04 より前のバージョンと同じ挙動。 4 API バージョン別のデフォルト挙動 API バージョン flattenComponents の既定 返り方 2026-04 以降 false トップレベルは親 line item のみ。構成品は DraftOrderLineItem.components から取得 2026-04 より前 true 親・構成品ともにトップレベルの node として返る（後方互換のため） つまり 2026-04 に上げると、明示指定しない限り返り方（nodes の中身）が変わる 。従来どおりフラットな一覧を前提に組んでいるコードは、 flattenComponents: true を明示するか、 components を辿る実装へ移行する必要がある。 5 サンプルクエリ（GraphQL） 記事に掲載されている例。親 line item の components をネストで取得している（既定の false 前提）。 query { draftOrder ( id : "gid://shopify/DraftOrder/1" ) { lineItems ( first : 10 ) { nodes { name quantity components { name quantity } } } } } nodes の各要素（親）の中に components をネストで書くだけ。フラットな従来挙動が欲しければ lineItems(first: 10, flattenComponents: true) のように引数を渡す。 6 技術者が押さえるべき5つのポイント 1. 対象は Customer Account API この変更は Customer Account API の話。マイページ等の「顧客自身がアクセスする」文脈で、下書き注文の構成品が見えるようになる。Admin API の同種変更とは別物として扱う。 2. 既定が変わるのは破壊的 2026-04 では flattenComponents が false 既定 。バージョンを上げると nodes の中身が「親だけ」に変わる。アップグレード時の最重要チェックポイント。 3. 引数で従来挙動に戻せる 移行を急げない場合は flattenComponents: true を明示すれば、2026-04 でも従来どおり親・構成品が同列で返る。段階的移行の逃げ道になる。 4. 構成品は components で辿る 既定挙動では、構成品は DraftOrderLineItem.components をクエリに追加しないと取得できない。フラット前提の集計ロジックは、親をループ → 子をループの二段に書き換える。 5. 記事に書かれていない範囲は要検証 component line item の型・取得できるフィールドの全容、ページネーション時の挙動、他 API（Admin / Storefront）との整合などは この記事には記載なし 。サンプルにある name / quantity 以外を使うなら、実バージョンのスキーマで確認すること。 7 業務に活かせる3つのユースケース USE CASE 1 顧客向けマイページで「バンドルの中身」を正しく表示 課題 下書き注文の確認画面で、バンドル商品が構成品まで一列にズラッと並び、「どれが本体でどれが中身か」が顧客に伝わらない。 打ち手 Customer Account API 2026-04 の既定（ネスト）を使い、親 line item を見出しに、 components をインデントした子リストとして描画。 効果 注文内容の視認性が上がり、構成品に関する問い合わせ・認識齟齬を削減。 技術メモ 親をループ → components をループの二段描画。 name / quantity は記事のサンプルで確認済みのフィールド。 USE CASE 2 2026-04 アップグレード時の「壊れない移行」設計 課題 既存の顧客アカウント実装が「nodes に親も構成品もフラットに来る」前提。バージョンを 2026-04 に上げると既定が変わり、表示や集計が崩れる恐れ。 打ち手 ① まず flattenComponents: true を明示してバージョンだけ先行で上げる → ② その後、 components を辿るネスト実装へ段階移行。 効果 API バージョン更新とロジック改修を分離でき、リリースリスクを最小化。 技術メモ 「2026-04 より前は true 既定／以降は false 既定」という非対称を理解し、引数を 明示する のが安全。 USE CASE 3 下書き見積もりの「親 / 構成品」を分けて明細化 課題 B2B 等の下書き注文（見積もり）を外部システムへ連携する際、親商品と構成品が混在し、明細の集計単位が揃わない。 打ち手 ネスト構造のまま取得し、親 line item を「明細行」、 components を「内訳行」として階層を保ったまま PDF / 帳票へ出力。 効果 見積書・納品書で構成品の内訳が明示され、承認・経理側の確認がスムーズに。 技術メモ 集計時はフラット（ true ）、表示時はネスト（ false ）と、用途で flattenComponents を使い分けるとロジックが素直になる。 8 提案で使える1行サマリ 「Customer Account API 2026-04 で、下書き注文の構成品を 親子ネストで取得 できるように。 components フィールド追加＋ flattenComponents 引数で従来のフラット挙動とも切替可能。 ただし 2026-04 は既定が false（ネスト）に変わるので、アップグレード時は明示指定で守る。 」 source ： shopify.dev / changelog / line-item-components-draft-orders-customer-account-api published 2026-04-01 ``` Want me to write this to `site/public/raw/260401_line-item-components-draft-orders-customer-account-api.html`? If so, approve the write and I'll save it there.