ギフトカードのローカル通貨対応がGraphQL Admin APIに追加

8月 10, 2026

API CHANGE

ギフトカードのローカル通貨対応
GraphQL Admin API 2026-07

発行通貨の固定・クロスカレンシー換算が制御可能に。initialValueは非推奨、initialAmountへの移行が必要。

OVERVIEW

01この変更の概要と影響範囲

2026-07バージョンのGraphQL Admin APIから、ギフトカードを特定通貨で発行・換算制御できる機能が追加されます。多通貨ストアを運営するマーチャント向けのアプリ開発者は、giftCardCreateで使用しているinitialValueフィールドを2026-07にアップグレードする前にinitialAmountへ必ず置き換える必要があります。

※ 本記事はShopify公式Changelogをもとにした独立系メディアの解説です。実装前は必ず公式ドキュメントをご確認ください。

MECHANISM

02仕組みの図解：発行通貨×換算戦略の組み合わせ

BEFORE / AFTER

03APIフィールドの変更点（Before/After）

USE CASES

04業務に活かせる具体ユースケース

課題: 日本円専用のブランドギフトカードを販売したいが、海外顧客が異なる通貨で購入・換金できてしまう問題がある
打ち手: issuanceCurrency: JPYを設定してギフトカード商品を作成し、JPYをサポートするマーケットのみに公開する。crossCurrencyRedeemable: falseで換算を禁止する
効果: 円建て資産として管理できるため、為替変動リスクをゼロにしつつ、日本市場向けのブランド価値を維持できる
技術メモ: giftCardProductSetミューテーション実行時にissuanceCurrencyとcrossCurrencyRedeemableを同時に設定。作成後の変更は不可

課題: グローバル展開するストアでギフトカードを発行しているが、通貨ごとに個別管理が煩雑で、顧客が複数通貨でシームレスに使えない
打ち手: デフォルト通貨で発行（issuanceCurrencyを未設定）し、crossCurrencyRedeemable: trueを設定することでMARKET_FX換算を有効化する
効果: 顧客は自国通貨でギフトカードを受け取り、別通貨のマーケットでもマーケットレートで換算されて利用可能になる
技術メモ: GiftCard.crossCurrencyRedemptionStrategyをクエリして換算方式を取得し、チェックアウトUIに表示する実装が推奨される

課題: ギフトカード作成アプリでinitialValueを使用しているが、APIバージョンアップ時に動作しなくなるリスクがある
打ち手: giftCardCreateのinitialValueをinitialAmount（amountとcurrencyCodeを含むオブジェクト）に置き換えて、2026-07アップグレード前にリリースする
効果: APIの非推奨フィールドによる突然の障害を防ぎ、同時に通貨情報も明示的に管理できるようになる
技術メモ: initialAmountはMoneyInputオブジェクト形式（amount + currencyCode）。既存のgiftCardCreateを呼び出す箇所を全て置き換える必要がある

DEVELOPER NOTES

05技術者目線のポイント

新ミューテーション
giftCardProductSetでギフトカード商品の作成・更新が可能に。issuanceCurrency・crossCurrencyRedeemable・バリアントへの設定が自動適用される

設定の不変制約
issuanceCurrencyとcrossCurrencyRedeemableは商品作成時のみ設定可能。後から変更不可のため、設計段階での慎重な決定が必要

非推奨フィールド対応
giftCardCreateのinitialValueは非推奨。2026-07へ移行前にinitialAmount（amount + currencyCode）への置き換えが必須

換算戦略の3パターン
NONE（同一通貨のみ）/ MARKET_FX（マーケットレート）/ SPOT_FX（スポットレート）。組み合わせは設定値によって自動決定される

クエリで換算状態を確認
GiftCard.isRedeemableとGiftCard.crossCurrencyRedemptionStrategyをクエリすることで、換金可否と換算方式を取得してUIに反映できる

マーケット公開の注意点
特定通貨を設定したギフトカード商品は、その通貨がサポートされているマーケットにのみ公開すること（元記事記載）

項目	内容	備考
対応APIバージョン	2026-07〜	それ以前は非対応
新ミューテーション	`giftCardProductSet`	作成・更新両対応
非推奨フィールド	`initialValue`	→ `initialAmount`へ移行
換算戦略	NONE / MARKET_FX / SPOT_FX	設定値から自動決定
設定変更可否	issuanceCurrency / crossCurrencyRedeemable	作成時のみ・変更不可
確認クエリ	GiftCard.isRedeemable / crossCurrencyRedemptionStrategy	換金可否・換算方式の取得