metafieldInteger廃止と2027-01移行ガイド

11月 03, 2026

BREAKING CHANGE

metafieldInteger廃止と2027-01移行ガイド

コレクション条件のmetafieldIntegerはAPI 2027-01で完全削除。今すぐmetafieldIntへ移行を。

Admin GraphQL APIのコレクション条件において、API 2027-01からmetafieldIntegerが完全削除されます。影響を受けるのはコレクションの自動振り分け条件を整数メタフィールドで管理しているアプリ・カスタム実装です。2026-10で動作確認のうえ、2027-01リリース前に移行を完了させる必要があります。

1何が変わるのか — Before / After 図解

2型・フィールドの置き換え対応表

旧 (削除対象)	新 (移行先)	変更点
CollectionSourceInclusionConditionMetafieldInteger	CollectionSourceInclusionConditionMetafieldInt	型名変更 / value: Int→String
CollectionSourceInclusionConditionMetafieldIntegerRelation	CollectionSourceInclusionConditionMetafieldIntRelation	型名変更のみ・enum値は同じ
CollectionSourceInclusionConditionInput.metafieldInteger	CollectionSourceInclusionConditionInput.metafieldInt	フィールド名変更 / value型変更
CollectionSourceInclusionConditionUpdateInput.metafieldInteger	CollectionSourceInclusionConditionUpdateInput.metafieldInt	フィールド名変更 / value型変更

3業務ユースケース

課題: 在庫数を整数メタフィールドで管理し、コレクション自動振り分けに利用しているカスタムアプリが2027-01移行後にエラーを起こす
打ち手: mutationのconditionsToCreate / conditionsToUpdateで使用しているmetafieldIntegerキーをmetafieldIntに置き換え、valueの値を数値リテラルから文字列リテラルに変更する
効果: 2027-01以降もコレクション条件の書き込み処理が正常動作し、在庫連動コレクションが継続稼働する
技術メモ: value: 2000 → value: "2000" と型だけ変更。relation (EQUALS/GREATER_THAN/LESS_THAN) はそのまま流用可

課題: コレクション条件を読み取り、管理画面にレポート表示するアプリでFragment指定のままだと型エラーが発生する
打ち手: queryのinline fragmentを ... on CollectionSourceInclusionConditionMetafieldIntegerから... on CollectionSourceInclusionConditionMetafieldIntに書き換える
効果: Read系クエリが2027-01以降もエラーなく動作し、条件データの取得・表示が維持される
技術メモ: 2026-10では整数メタフィールド条件がCollectionSourceInclusionConditionMetafieldIntとして解決されるため、この版でQueryのテストが可能

課題: 複数のShopifyストアに同一アプリを提供しているパートナーが、API移行のテストを本番ストアのみで実施しておりリスクが高い
打ち手: 2026-10バージョンを使い開発用ストアでmetafieldIntの書き込み・読み取りをサンドボックス確認し、問題なければ2027-01のリリース前に全ストアへデプロイ
効果: 本番環境での突発障害を回避しつつ、計画的に全ストアのAPI移行を完了できる
技術メモ: 2026-10時点でmetafieldIntegerはまだ動作するため、旧コードを残した状態で新コードの並行テストも可能

4技術者が押さえるべき5つのポイント

BREAKING

2027-01で完全削除

metafieldIntegerを含むmutationはバリデーションエラーで失敗。クエリはエラーを返す。後回しにできない変更。

型変更

valueがInt→String

最も見落としやすい変更点。JSONペイロードのvalue値を引用符なし整数から文字列に変更する必要がある。GraphQL型チェックで弾かれる。

テスト

2026-10でドライラン可能

2026-10バージョンでmetafieldIntの書き込み・読み取りを事前確認できる。2026-10ではmetafieldIntegerも並行動作するため安全に検証可能。

互換維持

relationのenum値は変更なし

EQUALS / GREATER_THAN / LESS_THAN はそのまま使用可。条件ロジック自体の書き直しは不要で、フィールド名とvalue型の2点のみ対応する。

整合性

Storefront APIとの型統一が目的

変更の背景はStorefront APIのMetafield.valueフィールドとの型統一。String型に統一することでフロント/バック間の実装が一貫する。

5移行チェックリスト

確認項目	対応内容	期限
mutationのフィールド名	metafieldInteger → metafieldInt に変更	2027-01移行前
mutationのvalue型	数値リテラル → 文字列リテラルに変更	2027-01移行前
queryのFragment型名	MetafieldInteger → MetafieldInt に変更	2027-01移行前
updateInputのフィールド名	metafieldInteger → metafieldInt に変更	2027-01移行前
2026-10での動作確認	開発ストアでmetafieldIntの書き込み・読み取りをテスト	2027-01移行前