Shopify Subscription APIs を掘り下げて分かったこと
Shopify Subscription APIs を掘り下げて分かったことをまとめます。
Subscription APIs の概要
2021年1月に Shopify Subscription APIs がリリースされ、今までサードパーティアプリに頼っていた 定期購入（サブスクリプション） の機能を Shopify の公式 API からも利用できるようになりました。
Shopify・アプリ間の責任区分
定期購入が公式 API でサポートされましたが、Shopify がその機能のすべてを担う訳ではなく、「Shopify」と「アプリ」との間で責任区分があります。
（Shopify subscriptions overview より引用）
Shopify は基本的に「データ管理」と「決済処理」のみを担います。それ以外の「管理画面での操作性」や「請求処理の呼び出し」などはアプリ側に委ねられます。
アプリがやるべきことの例
アプリがやるべきことは、ライフサイクル（下図）でいうと赤枠の部分です。管理画面の提供、ウェブフックの受け取り、データの作成・更新、請求処理の呼び出しなどを担います。
（Shopify subscriptions overview より引用）
APIリソースの構成
Subscription APIs は次の3つのリソースで構成されます。
1. Selling plan APIs
定期購入プランに関するリソースです。含まれる商品や請求頻度、割引方針などから構成されます。
（Create and manage selling plans より引用）
2. Subscription contract APIs
定期購入した顧客との契約に関するリソースです。
（Create and manage subscription contracts より引用）
初回決済が完了すると SubscriptionContract と Order が作成されます。それ以降は、アプリ側で SubscriptionContract を参照して請求処理を実行します。
更新処理は SubscriptionDraft を作成してから SubscriptionContract にコミットさせる仕様になっています。
3. Customer payment method APIs
決済に使う顧客の支払情報に関するリソースです。ドキュメントでは Mutations が記載されていますが、基本的には読み取り専用のリソースになると思います。
For security reasons, customer payment methods, such as credit cards, can't be updated using the API. Customers must request a second email that redirects them to a secure flow where credit card information can be safely updated.
（Create a secure customer-facing subscription portal より引用）
必要なアクセススコープ
Subscription APIs 関連のアクセススコープ（例えば、read_own_subscription_contracts）を申請なしでアプリのスコープに含めると、承認フローに入る前に 400 エラーが出ます。
Oauth error missing_shopify_permission: read_own_subscription_contracts
アクセススコープの申請
Subscription APIs の利用に必要なアクセススコープは、Partner Dashboard から「App setup > Subscriptions」から申請します。
申請するとレビュー中に更新され、Shopify Support からも自動メールがきます。"This may take up to 7 business days." とあるので、早めに申請しておいた方がよいでしょう。
承認されるとメールで連絡がきます。Partner Dashboard のステータスも更新されます。
認可されたのは、以下2つのアクセススコープです：
read_customer_payment_methods
write_own_subscription_contracts
【注意💥】own_subscription_contracts の意味
own_subscription_contracts スコープで許可されるのは、自身が作成した SellingPlan, SubscriptionContract に対する処理のみです。
したがって、たとえ write_own_subscription_contracts が認可されたとしても、別アプリで作成された定期購入のデータは操作できません。
試しに PayWhirl を使って定期購入をおこない、 read_own_subscription_contracts 権限で GraphQL の subscriptionContracts を叩いてみましたが、 edges が空 [] で返ってきました。クエリは次の通りです：
<<-'GRAPHQL'
query {
subscriptionContracts(first: 10) {
edges {
cursor
node {
id
status
}
}
}
}
GRAPHQL
☠️ all_subscription_contracts は非公開
一方、ドキュメントにもチラホラ記載のある all_subscription_contracts なら、別アプリで作成されたデータも含めた権限がありそうですが、Shopify Partner Support に問い合わせてみると「現時点では非公開」とのことでした：
At this time, the access scope for
read_all_subscription_contractsis only available to apps developed by Shopify. I would recommend subscribing to the Shopify News: What’s New for Shopify Partners Blog for updates to see if this is something we add in the future.
なので、別アプリで作成された SellingPlan, SubscriptionContract のデータは、現状、それらのアプリが提供する API から直接取得するしかありません。（また、今後 all_subscription_contracts が公開される保証もないです。）
まとめ
- 定期購入の機能が Shopify GraphQL API で使えるようになった
- とはいえ、Shopify がすべての機能を担うのではなく、Shopify・アプリ間の責任区分がある
- アプリがやるべきことは、管理画面の提供、ウェブフックの受け取り、データの作成・更新、請求処理の呼び出しなど
- Subscription APIsは、
Selling plan APIs,Subscription contract APIs,Customer payment method APIsの3つから成る - Subscription APIs の利用には、アクセススコープの申請が必要
-
own_subscription_contractsで許可されるのは自身が作成したSellingPlan,SubscriptionContractに対する処理のみ - 全ての
SellingPlan,SubscriptionContractにアクセスできるall_subscription_contractsは現時点では非公開
Discussion