バリエーションが 「複数バーコード」に対応 — barcode は非推奨へ

図解 ： Shopify バリエーションが複数バーコードに対応（barcodes connection） Developer Changelog / Admin GraphQL API バリエーションが 「複数バーコード」に対応 — barcode は非推奨へ 1 バリエーション ＝ 1 バーコードだった制約が外れ、UPC / EAN / ISBN / GTIN / ASIN を型付きで最大 20 件まで保持できるようになった。従来の barcode フィールドは動き続けるが deprecated。読み取りだけを続けると「他のバーコードの存在に気づけない」状態になる。 このページの構成 30秒で理解 ： 何が変わったのか 仕組み図解 ： 読み書きの経路 扱えるバーコードタイプと検証 利用上のルール（数量・上書き・排他） barcode（非推奨）との互換動作 最大の落とし穴 ： サイレント切り捨て 移行の 3 ステップ 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 30秒で理解 ： 何が変わったのか 同じバリエーションを、メーカーの UPC ／ プライベートブランドの EAN ／ GTIN ／ 再発行された ISBN ／ マーケットプレイス用の ASIN …と複数の識別子で売る現場は多い。 これまではバリエーションが持てるバーコードが 1 件だけ だったため、余りはメタフィールド・タグ・あるいは Shopify の外に逃がすしかなかった。 今回、複数バーコードが正式なデータ構造になった。 従来 ： 1 件しか入らない 2 つ目以降の識別子はメタフィールド／タグ／外部システムに退避。どこに何が入っているかがストアごとに属人化していた。 今後 ： 型付きで最大 20 件 ProductVariant.barcodes connection で読み、 barcodes input で書く。タイプを宣言すれば規格ルールで検証される。 書き込みに使えるミューテーションは productSet ／ productVariantsBulkCreate ／ productVariantsBulkUpdate の 3 つ。いずれも barcodes input を受け付ける。 2 仕組み図解 ： 読み書きの経路 検索側も追随済み ： products と productVariants クエリの barcode フィルタは、バリエーションが持つ いずれかの バーコードにマッチするようになった。先頭だけしか引っかからない、ということはない。 3 扱えるバーコードタイプと検証 各バーコードは type を宣言できる。宣言した場合、その規格の 文字種・桁数・プレフィックス・チェックディジット のルールに従って検証される。 UPC EAN ISBN GTIN ASIN type あり 規格に沿って検証される 文字種・長さ・プレフィックス・チェックディジットのルールに合致しない値はエラー。データ品質を API レイヤで担保できる。 type なし 送った値をそのまま保存 タイプを宣言しなければ、送信された値がそのまま格納される。 型なしの既存データは今まで通り動く ので、一括で型付けし直す必要はない。 4 利用上のルール（数量・上書き・排他） ルール 内容 実装上の意味 件数上限 20 件 / バリエーション 21 件目を入れたいケースは設計を見直す（別バリエーション or メタフィールド） 文字数上限 255 文字 / 1 バーコード 実運用の識別子には十分。連結値を詰め込む用途ではない 並び順 最初に送った値が connection の先頭にソートされる 「主識別子」を先頭に置く設計が可能 書き込み挙動 全置換 barcodes 送信はセット全体を置き換える 残したいバーコードも必ず含めて送る 。差分パッチではない 排他制約 不可 1 つの variant input で barcode と barcodes の両方は設定できない 移行期のコードで「両方セット」を書くと落ちる。どちらか一方に寄せる 検索フィルタ products / productVariants の barcode フィルタは任意の 1 件にマッチ サブ識別子で検索してもヒットする 「全置換」がいちばん事故りやすい ： 1 件だけ追加したいつもりで barcodes: [新しい値] を送ると、既存のバーコードは全部消える。必ず 読み取り → マージ → 全件送信 の順で実装すること。 5 barcode（非推奨）との互換動作 ProductVariant.barcode は非推奨になったが、 今日時点で壊れるものは何もない 。挙動は「常に connection の先頭を指す」と覚えれば足りる。 読み取り barcode を読むと、 barcodes connection の先頭のエントリ が返る。 書き込み barcode への書き込みは 先頭の 1 件だけ を更新し、 他のバーコードには触れない 。 空値の送信 空値を送ると先頭がクリアされ、 セット内の次のバーコードが繰り上がる 。以降、残りが無くなるまで同じ挙動。 先頭ポジションのバーコードを足したり差し替えたりすることで、 まだ移行できていない画面や連携先の見え方をコントロールしつつ 、複数バーコードの恩恵は受けられる。移行を段階的に進めるための逃げ道として使える。 削除時期 ： 廃止日は将来のアナウンスで告知される予定。フィールドが無くなる前に API バージョン 1 つ分の予告期間 が置かれる、とされている。具体的な日付は記載なし。 6 最大の落とし穴 ： サイレント切り捨て 2 件目のバーコードが追加された瞬間から 、 barcode だけを読むインテグレーションは「そのうちの 1 件」しか見えず、 他が存在するというシグナルすら受け取れない 。 商品識別子を ERP・マーケットプレイス・POS・サプライヤーフィード に同期しているアプリは、読み取りを barcodes connection に移すこと。 7 移行の 3 ステップ 1 barcode の参照箇所を洗い出す コード内の barcode 読み取りを全部拾う。特に外部システムへ書き出している経路を優先。 2 読み取りを barcodes に差し替え connection で全件取得し、必要なら type で絞り込む。先頭 1 件でよい箇所も明示的に先頭を取る形に。 3 書き込みをマージ方式に barcodes は全置換なので「読む → マージ → 全件送る」に。 barcode との併用は不可なので片方に統一。 8 技術者が押さえるべき5つのポイント 1. 書き込みは差分ではなく「全置換」 barcodes を送るとバリエーションのセット全体が置き換わる。 残したいものを含めて送る のが必須。既存アプリの update 系コードをそのまま流用すると全消しになる。 2. barcode と barcodes は排他 1 つの variant input で両方を設定することはできない。移行途中で「安全のため両方書く」実装は成立しないので、経路ごとにどちらを使うか決め切る。 3. type 宣言＝バリデーションの導入 UPC / EAN / ISBN / GTIN / ASIN を宣言すると、文字種・長さ・プレフィックス・チェックディジットが検証される。 型を付けた瞬間、今まで通っていた汚いデータが弾かれる 可能性がある点に注意。 4. 「先頭」が後方互換の要 レガシー画面や未移行の連携先が見るのは常に先頭。 先頭に何を置くかがそのまま互換性の設計 になる。移行順に合わせて主識別子を先頭に固定しておくと事故が減る。 5. 一番怖いのは「エラーが出ない劣化」 サイレント切り捨ては例外も警告も出さない。 ERP / マーケットプレイス / POS / サプライヤーフィードへ識別子を同期しているアプリ は、明日壊れなくても「静かに間違ったデータを流し続ける」状態になり得る。廃止日は未定（将来告知＋API バージョン 1 つ分の予告）だが、 移行の緊急度は廃止日ではなくデータ整合性で決まる 。 9 業務に活かせる3つのユースケース USE CASE 1 メタフィールドに散らばった識別子を正規のデータ構造へ集約 課題 1 バリエーション ＝ 1 バーコードの制約のせいで、2 つ目以降の UPC / EAN / GTIN がメタフィールド・タグ・Shopify 外のスプレッドシートに散らばり、どれが正なのか誰も分からない。 打ち手 散在している識別子を棚卸しし、 productVariantsBulkUpdate の barcodes input で 1 バリエーションに集約。規格が分かるものは type を宣言して検証を通す。 効果 識別子の置き場が 1 か所に定まり、検索も barcode フィルタで全件横断できる。棚卸し過程で不正な値も洗い出せる。 技術メモ 上限は 20 件 / 各 255 文字。移行スクリプトは全置換仕様なので「既存の全件 ＋ 追加分」をまとめて送る形にする。 USE CASE 2 ERP / POS / マーケットプレイス連携の「静かなデータ欠損」を防ぐ健全性チェック 課題 自社・受託の連携アプリが barcode 1 件だけを読んで外部へ同期している。マーチャント側が 2 件目のバーコードを登録した瞬間から、外部システムには不完全な識別子が流れ続ける（警告は出ない）。 打ち手 連携コードの barcode 参照を洗い出し、 barcodes connection 読みに置換。移行前の暫定対応として「バーコードが 2 件以上あるバリエーション」を抽出してレポート化する。 効果 マーケットプレイス出品エラー・入荷検品ミス・サプライヤーフィードの不一致といった、原因究明に時間のかかる障害を事前に潰せる。 技術メモ 抽出は productVariants を舐めて barcodes の件数を見る。廃止日は未定だが、 影響は廃止前から発生する 点が要注意。 USE CASE 3 型付きバーコードで商品マスタのデータ品質を API 側に担保させる 課題 チェックディジット違いや桁数不足の UPC / EAN が商品マスタに混入し、出品や検品の段階で初めて発覚する。バリデーションを自前実装するとメンテコストがかかる。 打ち手 取り込み時に type （UPC / EAN / ISBN / GTIN / ASIN）を宣言して書き込み、Shopify 側の検証を通す。規格が特定できない値は type 未宣言のまま送り、現状維持で保存する。 効果 不正な識別子を投入時点で弾ける。自前バリデータの保守が不要になり、規格ルールの更新も Shopify 側に委ねられる。 技術メモ 型を付けると既存の不正データが弾かれ得るため、 まず dry-run 相当で検証エラー件数を可視化 してから本適用するのが安全。type 未宣言なら値はそのまま保存され、従来の挙動と変わらない。 10 提案で使える1行サマリ 「1 バリエーション ＝ 1 バーコードの制約が外れ、UPC / EAN / ISBN / GTIN / ASIN を型付きで最大 20 件まで持てるようになった。 従来の barcode は非推奨だが今日は壊れない。ただし 2 件目が登録された瞬間から、 barcode しか読まない連携は静かに識別子を取りこぼす。 ERP・POS・マーケットプレイス連携がある案件は、廃止日を待たず読み取りを barcodes へ移すのが先。」 source ： shopify.dev / changelog / product-variant-barcode-is-being-replaced-by-barcodes published 2026-09-08 ／ generated 2026-09-09