サブスク mutation に actor フィールドが追加

図解 ： Shopify サブスク mutation に actor フィールド追加 Admin GraphQL API 2026-07 サブスク mutation に actor フィールドが追加 サブスクリプションの課金・契約編集・ステータス変更を「誰が起点で行ったか」（顧客 / マーチャント / パートナーアプリ）を、mutation 実行時に記録できるようになった。 このページの構成 何が変わるのか（30秒で理解） actor の 3 つの値 仕組み図解 ： アクションに「発生源」が刻まれる 対応する Admin API ミューテーション一覧 記載されていること / されていないこと 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 何が変わるのか サブスクリプション関連の mutation に actor 引数が新設された。 課金の作成や契約の編集を行うときに、 そのアクションを起こしたのが「顧客」「マーチャント」「パートナーアプリの自動システム」のどれか を一緒に記録できる。 従来 ： 「何が起きたか」だけ 課金作成や契約変更は記録されるが、その操作を 誰が起点で発火させたか はミューテーションの引数として標準化されていなかった。 追加後 ： 「誰が起点か」も渡せる actor に customer / merchant / partner を指定して、操作の発生源を明示できるようになった。 2 actor の 3 つの値 customer 顧客が起点 買い手がアクションを開始した場合。例 ： カスタマーポータルで「今すぐ支払う（pay now）」をクリックした、など。 merchant マーチャントが起点 マーチャントまたはそのスタッフが手動でアクションを開始した場合。 partner パートナーアプリが起点 パートナーアプリの自動システムが開始した場合。例 ： スケジュール課金やリトライ（再試行）ロジック、など。 3 仕組み図解 ： アクションに「発生源」が刻まれる subscriptionBillingAttemptCreate だけは subscriptionBillingAttemptInput.actor として入力オブジェクト経由で渡す、と記事に明記されている。それ以外は mutation の引数として actor を含める。 4 対応する Admin API ミューテーション一覧 記事に列挙されている対応ミューテーションは、用途別に次の3グループ。 グループ 対応ミューテーション 課金試行 Billing Attempts subscriptionBillingAttemptCreate （ subscriptionBillingAttemptInput.actor 経由） subscriptionBillingCycleCharge subscriptionBillingCycleBulkCharge 契約編集 Contract Edits subscriptionContractCreate subscriptionContractUpdate subscriptionContractAtomicCreate subscriptionContractProductChange subscriptionBillingCycleContractEdit ステータス更新 Status Updates subscriptionContractActivate subscriptionContractPause subscriptionContractCancel subscriptionContractFail subscriptionContractExpire 課金・契約編集・ステータス変更（再開/停止/解約/失敗/期限切れ）まで、 サブスクのライフサイクル操作のほぼ全面 で発生源を記録できる。 5 記載されていること / されていないこと ✅ 記事に明記されている ・ actor 引数の新設と目的（誰が起点かの追跡） ・取りうる3つの値（ customer / merchant / partner ）と各例 ・対応する13個のミューテーション（3グループ） ・ subscriptionBillingAttemptCreate のみ入力オブジェクト経由 ・API バージョンタグ ： 2026-07 ⚠️ 記事には記載なし（要検証） ・ actor が必須か任意か、デフォルト値 → 記載なし ・未指定時の挙動 → 記載なし ・記録された actor の読み取り（クエリ）方法 → 記載なし ・利用に必要なアクセススコープ / 権限 → 記載なし ・ actor が認証主体と一致するかの検証可否 → 記載なし 必須/任意・デフォルト・読み取り方法は記事に書かれていないため、導入前に対象 API バージョン（ 2026-07 ）のスキーマ／ドキュメントで確認すること。 6 技術者が押さえるべき5つのポイント 1. 値は enum 3種に固定 受け付けるのは customer / merchant / partner の3値のみ。送信側でこのいずれかを正しくマッピングして渡す設計が必要。 2. 課金作成だけ渡し方が違う subscriptionBillingAttemptCreate は引数直下ではなく subscriptionBillingAttemptInput.actor に入れる。共通化したクライアント実装では分岐が要る。 3. 横断適用なので一括対応が要る 課金・契約編集・ステータス更新の13ミューテーションに渡る。自前のサブスク連携コードで、呼び出し箇所すべてに actor 設定方針を通すのが望ましい。 4. 必須/任意・既定値は未公表 記事に必須かどうか・デフォルト・未指定時の挙動の記載はない。サンドボックスで実挙動を確認してから本番ロジックを固めること。 5. API バージョン 2026-07 の機能 ／ 価値は「分析・監査」軸 記事のタグは 2026-07 。 actor は決済そのものを変える機能ではなく、 「誰が起点でそのサブスク操作を発火させたか」を構造化メタデータとして残す もの。チャーン分析・監査ログ・自動 vs 手動の切り分けに効く。記録値の読み取り方法は記事に記載がないため別途確認が必要。 7 業務に活かせる3つのユースケース USE CASE 1 解約・課金失敗を「発生源別」に分解してチャーン分析 課題 解約（cancel）や課金失敗（fail）が「顧客の自主解約」なのか「マーチャント運用による解約」なのか「自動リトライ枯渇による失敗」なのか区別できず、改善の打ち手が絞れない。 打ち手 ステータス更新・課金系ミューテーションで actor を必ず付与し、 customer / merchant / partner 別に解約・失敗を集計する。 効果 自主解約と運用都合・システム都合を分離でき、リテンション施策と課金リトライ設計をそれぞれ的確に打てる。 技術メモ 記録された actor の読み取り方法は記事に記載なし。集計前に対象 API バージョンで取得手段（クエリ）を確認すること。 USE CASE 2 サブスク操作の監査ログ ／ サポート問い合わせ対応 課題 「この契約は誰が変更/停止したのか」をサポートや監査で問われても、操作の起点（顧客自身か、スタッフ操作か、自動処理か）が追えない。 打ち手 契約編集・ステータス更新の各ミューテーションに actor を付け、操作の起点を構造化メタデータとして残す。 効果 サポート時の説明責任が果たせ、顧客起点の操作とスタッフ操作・自動処理を明確に切り分けられる。 技術メモ カスタマーポータルの操作は customer 、管理画面のスタッフ操作は merchant 、バックエンドの自動処理は partner をマッピングする実装方針を統一する。 USE CASE 3 自動リトライ／定期課金（partner）の挙動を可視化・最適化 課題 パートナーアプリのスケジュール課金・リトライロジックが生む課金試行が、顧客起点の支払いと混ざってログ上区別できず、リトライ設計の効果検証ができない。 打ち手 自動処理が発火する課金作成（ subscriptionBillingAttemptCreate など）には partner を付与し、顧客の「今すぐ支払う」は customer として分離記録する。 効果 自動リトライ由来の成功/失敗率を独立して測定でき、リトライ間隔・回数のチューニング根拠データが得られる。 技術メモ subscriptionBillingAttemptCreate は subscriptionBillingAttemptInput.actor 経由で渡す点に注意。スケジューラ／リトライ経路のコードに固定で partner を埋め込む。 8 提案で使える1行サマリ 「サブスクの課金・契約編集・ステータス変更を 『顧客 / マーチャント / パートナーアプリ』のどれが起点か で記録できる actor フィールドが追加（API 2026-07 ）。 チャーン分析・監査ログ・自動 vs 手動の切り分けが、追加実装の発生源タグ付けだけで実現できる。」 source ： shopify.dev/changelog/add-actor-field-to-subscription-contract-and-billing-attempt-mutations Developer Changelog ／ 公開日 2026-05-01（ページ表記 May 4, 2026）／ generated 2026-05-23