orderCreateでカスタムIDによる注文作成が可能に

11月 11, 2026

GraphQL Admin API

orderCreate でカスタムIDによる注文作成が可能に

外部システムのIDをそのまま渡して注文を作れる variantIdentifier が安定版へ

このアップデートは orderCreate ミューテーションを利用するアプリ開発者・販売チャネル連携担当者 に影響します。GraphQL Admin API バージョン 2027-01 以降 から variantIdentifier フィールドが安定版に昇格し、外部システムのIDをメタフィールド経由で直接指定して注文を作成できるようになりました。これまで必要だった「外部ID → Shopify variant ID」の事前変換ステップが不要になります。

1Before / After で見る変更点

2具体的なユースケース

課題: ECモールや自社基幹システムの商品IDとShopifyのvariant IDが異なり、注文連携時に毎回ID変換が発生していた
打ち手: 各バリアントのメタフィールド（例: custom.listing_id）に外部IDを格納し、orderCreate の variantIdentifier.customId にそのまま渡す
効果: ID変換用の中間テーブル管理が不要になり、連携ロジックを大幅にシンプル化できる
技術メモ: メタフィールド定義は type id で product variants に設定が必要。定義が存在しない場合は INVALID エラーが返る

課題: OMS（受注管理システム）からShopifyへ注文を流し込む際、variant IDを都度APIで引いてからorderCreateを呼ぶ2段階処理になっていた
打ち手: OMS側の注文データに含まれる商品コードをvariantのメタフィールドに対応付けておき、連携バッチを1リクエスト構成に変更する
効果: API呼び出し回数が半減し、タイムアウトやレートリミットのリスクを低減できる
技術メモ: variantIdentifier と variantId / productId を同一行項目に併用した場合、INVALID コードのユーザーエラーが返るため、移行時は排他的に使用すること

課題: 複数の販売チャネル（実店舗POS、外部ECサイト、マーケットプレイス）それぞれが異なるSKUコード体系を持ち、Shopify側でのID管理が複雑化していた
打ち手: チャネルごとに専用の namespace（例: pos、marketplace）を持つメタフィールド定義を用意し、各チャネルアプリが自分の namespace を使って注文作成する
効果: チャネルごとのID体系を維持したまま、統一的なorderCreate処理を実装できる
技術メモ: namespaceを省略した場合はアプリの予約済み namespace が自動使用される。カスタムIDの検索はアプリが読み取り可能なメタフィールドのみ対象となる

3技術者向け実装ポイント

📋 前提条件チェックリスト

対象ストアに type id のメタフィールド定義が product variants に存在すること
アプリがそのメタフィールドを読み取れる権限を持つこと
各バリアントの該当メタフィールドに外部IDが格納済みであること

⚠️ エラーコード一覧

INVALID variantIdentifier と variantId/productId の併用
INVALID メタフィールド定義が存在しない場合
VARIANT_IDENTIFIER_NOT_FOUND 一致するバリアントが見つからない場合（注文は作成されない）

項目	内容
対象APIバージョン	2027-01 以降（unstable では先行提供済み）
対象外バージョン	2026-10 以前は variantIdentifier フィールドなし
追加スコープ	不要（orderCreate が既に要求するスコープで利用可）
unstable からの移行	リクエスト変更不要。バージョン指定を 2027-01 に更新するだけ
既存 variantId 利用	従来通り動作（破壊的変更なし）
アクション要否	既存アプリへの影響なし。新機能は opt-in で利用

4実装サンプル（要点）

mutation orderCreate — variantIdentifier.customId の使い方

mutation {
  orderCreate(order: {
    lineItems: [{
      variantIdentifier: {
        customId: {
          namespace: "custom",
          key: "listing_id",
          value: "LST-10045"
        }
      }
      quantity: 1
    }]
  }) {
    order { id }
    userErrors { field message code }
  }
}

※ namespace を省略するとアプリの予約済み namespace が使用される。開発ストアで動作確認後、本番適用を推奨。

外部システムのIDをShopifyのメタフィールドに格納するだけで、orderCreate 1リクエストで注文作成が完結するため、OMSや販売チャネル連携の実装コストを大幅に削減できます。

Source: https://shopify.dev/changelog/ordercreate-line-items-support-custom-ids | 公開日: 2026年11月06日