SUBSCRIPTIONS / ADMIN API
サブスク操作の実行者を記録できる
actor フィールドが追加
誰が操作したかを GraphQL ミューテーションで明示できるように
Admin API のサブスクリプション関連ミューテーション全般に actor フィールドが追加されました。請求試行・契約編集・ステータス変更の各操作で、操作を起こしたのが顧客・マーチャント・パートナーアプリのいずれかを明示できます。2026年5月4日より利用可能です。
1Before / After：実行者の可視化
2対象ミューテーション一覧
| カテゴリ | ミューテーション名 | actor の渡し方 |
|---|---|---|
| 請求試行 | subscriptionBillingAttemptCreate | subscriptionBillingAttemptInput.actor |
| 請求試行 | subscriptionBillingCycleCharge | actor 引数 |
| 請求試行 | subscriptionBillingCycleBulkCharge | actor 引数 |
| 契約編集 | subscriptionContractCreate | actor 引数 |
| 契約編集 | subscriptionContractUpdate | actor 引数 |
| 契約編集 | subscriptionContractAtomicCreate | actor 引数 |
| 契約編集 | subscriptionContractProductChange | actor 引数 |
| 契約編集 | subscriptionBillingCycleContractEdit | actor 引数 |
| ステータス変更 | subscriptionContractActivate | actor 引数 |
| ステータス変更 | subscriptionContractPause | actor 引数 |
| ステータス変更 | subscriptionContractCancel | actor 引数 |
| ステータス変更 | subscriptionContractFail | actor 引数 |
| ステータス変更 | subscriptionContractExpire | actor 引数 |
3業務に活かせる具体ユースケース
- 課題
- カスタマーポータルでユーザーが「今すぐ請求」を押した際、アプリ側の自動リトライと区別できずサポート対応が混乱する
- 打ち手
- ポータルからの請求試行には
actor: customerを付与。自動リトライにはactor: partnerを付与し、ログで一目瞭然に分類する - 効果
- 問い合わせ時に「顧客自身が操作した請求」か「アプリが再試行した請求」かを即座に特定でき、サポート工数を削減
- 技術メモ
- subscriptionBillingAttemptCreate では subscriptionBillingAttemptInput オブジェクト内の actor フィールドに値を渡す点に注意（他ミューテーションと構造が異なる）
- 課題
- マーチャントが管理画面から手動でサブスク契約を一時停止したのか、アプリの自動ロジックが停止させたのかを後から判断できない
- 打ち手
- 管理画面の操作 UI から呼ぶ subscriptionContractPause には
actor: merchant、アプリ側バッチ処理からの呼び出しにはactor: partnerを付与してイベントログに保存する - 効果
- 監査ログの品質が上がり、「誰が止めたか」の責任所在が明確になることでマーチャントとの信頼関係を強化できる
- 技術メモ
- actor の値はミューテーションの応答には含まれない可能性があるため、呼び出し時のパラメータを自前のシステムにも記録しておくことを推奨（元記事に応答仕様の記載なし）
- 課題
- 請求失敗後のダンニングシーケンス（自動再試行）で複数回 subscriptionBillingCycleCharge が走り、どの試行が人手介入でどれが自動かを区別できない
- 打ち手
- スケジューラーからの定期実行は
actor: partner、サポートスタッフが管理ツールから手動実行する場合はactor: merchantと明示してデータウェアハウスに格納する - 効果
- BI ツールで「自動再試行成功率」と「手動介入成功率」を分けて集計でき、ダンニング戦略の改善に活用できる
- 技術メモ
- subscriptionBillingCycleBulkCharge でも同じ actor 引数が使えるため、バルク処理にも一貫して付与可能
4技術者が押さえるべきポイント
引数の場所に注意
subscriptionBillingAttemptCreate だけ subscriptionBillingAttemptInput.actor という入れ子構造。他のミューテーションはトップレベルの actor 引数として渡す。実装時は各ミューテーションのスキーマを個別に確認すること。
後方互換性
actor はオプショナルフィールドであるため、既存の実装を変更しなくても動作は継続する。段階的に対応ミューテーションへ追加していける。
利用できる値は3種類のみ
受け入れられる値は customer / merchant / partner の3種類のみ。元記事にそれ以外の値や将来拡張の記載はないため、不明な場合は最も近い値を選ぶ設計を検討する。
対象 API
Admin API のサブスクリプション系ミューテーション全13種が対象。Storefront API・REST Admin API への対応可否は元記事に記載なし。
ログ設計の推奨
actor フィールドが応答に含まれるか否かは元記事に明示がない。呼び出し側のシステムでパラメータをそのままログに残す設計を合わせて実装することを強く推奨する。
Source: https://shopify.dev/changelog/add-actor-field-to-subscription-contract-and-billing-attempt-mutations | 公開日: 2026年5月4日
Share:
管理画面インテント7種追加：設定画面をアプリから直接開く
appliesOnSubscriptionのデフォ値がtrueに変更