Shopify Subscription APIs を掘り下げて分かったこと

公開:2021/02/08
更新:2021/02/08
6 min読了の目安(約6200字TECH技術記事

Shopify Subscription APIs を掘り下げて分かったことをまとめます。

Subscription APIs の概要

2021年1月に Shopify Subscription APIs がリリースされ、今までサードパーティアプリに頼っていた 定期購入(サブスクリプション) の機能を Shopify の公式 API からも利用できるようになりました。

https://www.shopify.jp/blog/partner-api-release-january-2021

Shopify・アプリ間の責任区分

定期購入が公式 API でサポートされましたが、Shopify がその機能のすべてを担う訳ではなく、「Shopify」と「アプリ」との間で責任区分があります。

Shopify vs Shopify app の責任区分

Shopify subscriptions overview より引用)

Shopify は基本的に「データ管理」と「決済処理」のみを担います。それ以外の「管理画面での操作性」や「請求処理の呼び出し」などはアプリ側に委ねられます。

アプリがやるべきことの例

アプリがやるべきことは、ライフサイクル(下図)でいうと赤枠の部分です。管理画面の提供、ウェブフックの受け取り、データの作成・更新、請求処理の呼び出しなどを担います。

Subscription のライフサイクル

Shopify subscriptions overview より引用)

APIリソースの構成

Subscription APIs は GraphQL API でのみ公開されています。

Subscription APIs は次の3つのリソースで構成されます。

1. Selling plan APIs

https://shopify.dev/docs/admin-api/graphql/reference/products-and-collections/sellingplan

定期購入プランに関するリソースです。含まれる商品や請求頻度、割引方針などから構成されます。

Selling plan APIs の構成

Create and manage selling plans より引用)

2. Subscription contract APIs

https://shopify.dev/docs/admin-api/graphql/reference/object/subscriptioncontract

定期購入した顧客との契約に関するリソースです。

Subscription contract APIs の構成

Create and manage subscription contracts より引用)

初回決済が完了すると SubscriptionContractOrder が作成されます。それ以降は、アプリ側で SubscriptionContract を参照して請求処理を実行します。

更新処理は SubscriptionDraft を作成してから SubscriptionContract にコミットさせる仕様になっています。

3. Customer payment method APIs

https://shopify.dev/docs/admin-api/graphql/reference/object/customerpaymentmethod

決済に使う顧客の支払情報に関するリソースです。ドキュメントでは 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 エラーが出ます。

400 エラー

Oauth error missing_shopify_permission: read_own_subscription_contracts

アクセススコープの申請

Subscription APIs の利用に必要なアクセススコープは、Partner Dashboard から「App setup > Subscriptions」から申請します。

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_contracts is 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 は現時点では非公開

References