記事のサマリー（TL;DR）
- 2026-07 以降、POS経由ギフトカード払い出しは
GiftCardCashOutTransactionとして識別される - 2026-04 以前は同じ取引が
GiftCardDebitTransactionに分類されており、バージョン間で挙動が変わる __typenameフィールドを使うことで、払い出し・クレジット・デビットの3種類を正確に区別できる
国内 Shopify POS 導入企業・ギフトカード運用担当者が確認すべき移行ポイント
日本国内でも百貨店・アパレル・雑貨チェーンを中心に、Shopify POS とギフトカード機能を組み合わせた店舗運用が広がっています。今回の変更は GraphQL Admin API バージョン 2026-07（2026年7月以降のリリース） を境にギフトカード取引の型分類が変わるため、以下の点を事前に確認する必要があります。
1. 既存のギフトカード取引クエリの見直し
giftCard.transactions を取得しているすべての実装で __typename を参照しているかを確認します。2026-04 以前の API バージョンを使い続ける場合は GiftCardDebitTransaction のまま動作しますが、2026-07 以降に移行すると同じ POS 払い出し取引が GiftCardCashOutTransaction として返るため、型ごとのロジック分岐が必要になります。
2. 会計・在庫連携システムへの影響
kintone や Salesforce などと Shopify Admin API を連携して売上データを取り込んでいる場合、ギフトカード払い出しを「デビット」として処理しているロジックが誤分類につながる可能性があります。API バージョンアップ前に型マッピングを更新するのが安全です。
3. テスト環境での動作確認
Shopify は API バージョンの移行期間を設けているため、2026-07 を開発環境に固定し、GiftCardCashOutTransaction が正しく返るかをリリース前に検証することを推奨します。
詳細
GiftCardCashOutTransaction とは
GraphQL Admin API バージョン 2026-07 から、GiftCardTransaction インターフェースに新しいバリアントとして GiftCardCashOutTransaction が追加されました。この型は、POS（Point of Sale）システムを通じてギフトカード残高が現金として払い出される取引を専用に表現します。
これまで（2026-04 以前の API バージョン）、このような払い出し取引は GiftCardDebitTransaction（デビット取引）として分類されていました。2026-07 以降は同一の取引が GiftCardCashOutTransaction として識別されるため、API バージョンをまたぐ実装では注意が必要です。
クレジット・デビット・払い出しを正確に区別する方法
3種類のギフトカード取引（クレジット / デビット / 払い出し）を正確に区別するには、giftCard.transactions をクエリする際に __typename フィールドを使います。
以下は公式の実装例です。
giftCard(id: "...") {
transactions(first: 10) {
nodes {
__typename
... on GiftCardCashOutTransaction {
id
amount {
amount
currencyCode
}
}
}
}
}
__typename を取得することで、各ノードが GiftCardCashOutTransaction・GiftCardDebitTransaction・GiftCardCreditTransaction のいずれであるかをクライアント側で判定できます。インラインフラグメント（... on GiftCardCashOutTransaction）を組み合わせると、型ごとに必要なフィールドだけを取得できます。
バージョン別の動作まとめ
| API バージョン | POS払い出し取引の型 |
|---|---|
| 2026-04 以前 | GiftCardDebitTransaction |
| 2026-07 以降 | GiftCardCashOutTransaction |