ギフトカード精算取引を新型で識別｜API 2026-07

8月 09, 2026

API CHANGE

ギフトカード精算取引を新型で識別
GiftCardCashOutTransaction 登場

GraphQL Admin API 2026-07 から POS 精算が専用の型として分離される

GraphQL Admin API バージョン 2026-07 から、POS（店頭）でギフトカード残高を現金精算する取引が GiftCardCashOutTransaction という専用の型として正式に追加されます。これまで GiftCardDebitTransaction に混在していた精算取引を __typename フィールドで明確に識別できるようになり、取引種別ごとの集計・分析が容易になります。対象は Admin GraphQL API を利用してギフトカード取引を取得・分析しているすべての開発者です。

WHAT CHANGED

01変更内容の全体像

USE CASES

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

課題: 月次レポートでギフトカードの「利用額」と「現金精算額」を分けて集計したいが、従来の API では両者が同一の型で返ってくるため、手動フィルタリングが必要だった。
打ち手: giftCard.transactions クエリに __typename を含め、GiftCardCashOutTransaction と GiftCardDebitTransaction を別集計ロジックに振り分けるパイプラインを構築する。
効果: レポート用 ETL の手動補正ステップを廃止でき、精算額を自動で正確に計上できる。
技術メモ: API バージョンを 2026-07 以降に固定したうえで、... on GiftCardCashOutTransaction フラグメントで amount.amount / amount.currencyCode を取得すること。

課題: POS 端末での精算オペレーションが本当に正しく記録されているか、店舗スタッフが確認するダッシュボードがなく、不正利用の検知が困難だった。
打ち手: Admin API 経由で GiftCardCashOutTransaction のみを抽出し、精算額・日時・店舗の組み合わせで異常値検知アラートを実装する。
効果: 高額精算や短時間の連続精算をリアルタイムに検知でき、不正リスクを低減できる。
技術メモ: 現時点で取引のフィルタリングパラメータについて元記事の記載なし。取引量が多い場合はページネーション（first / after）と日時での絞り込みを組み合わせること。

課題: ギフトカード残高の会計処理において、負債として計上すべき「未使用残高」と費用処理すべき「精算済み残高」の区分が API レベルで取れず、経理部門の手作業が多かった。
打ち手: 定期バッチで GiftCardCashOutTransaction を集計し、会計システムへの仕訳データとして自動連携するアダプターを実装する。
効果: 精算取引を正確な勘定科目へ自動マッピングでき、月次決算の作業時間を短縮できる。
技術メモ: id・amount.amount・amount.currencyCode が公式サンプルに明示されているフィールド。他フィールドの可用性は公式ドキュメント（GiftCardCashOutTransaction オブジェクト定義）で確認を。

TECHNICAL NOTES

03技術者目線のポイント

🔢 対象 API バージョン

2026-07 以降。2026-04 以前では GiftCardCashOutTransaction 型は存在せず、POS 精算は GiftCardDebitTransaction として返る。バージョンを上げるまで既存動作は変わらない。

🧩 インターフェース設計

GiftCardCashOutTransaction は GiftCardTransaction インターフェースの新しいバリアント。既存の GiftCardDebitTransaction・GiftCardCreditTransaction と同じインターフェースを実装するため、共通フィールドはそのまま利用できる。

🔍 __typename による判別

公式推奨は __typename フィールドを giftCard.transactions クエリに含める方法。... on GiftCardCashOutTransaction のインラインフラグメントで型固有フィールドを安全に取得できる。

⚠️ 移行時の注意点

API バージョンを 2026-07 に上げると、それ以降の POS 精算取引は GiftCardDebitTransaction ではなく GiftCardCashOutTransaction で返る。DebitTransaction のみを前提とした集計・分岐ロジックは必ず見直すこと。

📋 確認済みフィールド

公式サンプルに明示されているフィールドは id・amount.amount・amount.currencyCode。その他フィールドは公式ドキュメントの GiftCardCashOutTransaction オブジェクト定義を参照のこと。

🏪 対象チャネル

元記事の説明によると、本型は POS（Point of Sale）システム経由の精算取引を表す。オンラインストアでの通常利用は従来どおり GiftCardDebitTransaction で表現されると考えられる（公式ドキュメントで要確認）。