目的

2021年1月にリリースにされた Shopify Subscription APIs について理解したことを列挙する。

Keisuke Inaba

概要（Shopify subscriptions overview）

Subscription APIs の構成

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

Selling plan APIs：商品（Products or Variants）を Subscription 販売するプラン
Subscription contract APIs：顧客とストア間の Subscription 契約
Customer payment method APIs：定期決済に使う顧客の支払情報

Shopify vs アプリの責任区分

データモデリング、データ保存、決済周りは Shopify が担う。
請求、サブスクの管理などはアプリ（サードパーティ）が担う。

Shopify vs Shopify app の責任区分

アプリが気にすべきこと

アプリが気にすべきことは、ライフサイクルでいうと赤枠の部分。責任区分にあった通り、プランの作成、請求、サブスクの管理、ウェブフックの受け取りなどを行う。

Subscription のライフサイクル

UXガイドライン

Shopify の既存のワークフローに合わせる
Shopify がすでに持っているデータは、そのリソースを参照して使う
Product subscription app extension の利用が求められる

Product subscription app extension

Shopify 管理画面の products ページ内から subscription をいじれるようにする app extension。

App proxy

顧客が Subscription の情報を変更するための UI を、Shopify ストアから遷移せずに提供するための仕組み。

Storefront Liquid drops and properties

Subscription のオプションを商品ページに表示するためのテンプレート（テーマ用）。

Keisuke Inaba

紹介記事（Introducing Shopify Subscription APIs）

正式リリース前に Shopify Subscription の PM の人が書いた紹介記事。

簡単なデモ動画（GIF）

必要なアクセススコープ

アプリ開発で Subscription APIs を使うには、次のアクセススコープが必要。

read_customer_payment_methods
write_own_subscription_contracts

上記アクセススコープの取得にはShopifyの承認が必要。「Partner Dashboard > App setup > Subscriptions」の「Request access to Subscription APIs」から申請できる。

Keisuke Inaba

Product subscription app extension の概要

できること

Shopify 管理画面の products ページ内から subscription をいじれるようにする app extension。

Product subscription app extension の概要

Argo というフレームワークを使って JavaScript, React, TypeScript などの言語で実装する。Argo を使うと、iframe 的に Shopify 管理画面の内側で描画できるという理解。

Argo

チュートリアル

ひな形の作成

構成・ベストプラクティスなど

デプロイ

Keisuke Inaba

アクセススコープについて

アクセススコープ一覧は必ずしも最新ではないので、今回リリースされた API の関連スコープが載ってなかったりする。

必要なアクセススコープ

SellingPlan

all or app-owned selling plans とあるが、以下のチュートリアルでも write_own_selling_plans のようなスコープは出てこないので詳細は不明。

SubscriptionContract

おそらく次のようなアクセススコープになる：

read_all_subscription_contracts
write_all_subscription_contracts
read_own_subscription_contracts
write_own_subscription_contracts

上のチュートリアル「Create and manage selling plans」でも出てきているので、これで合ってると思われる。

CustomerPaymentMethod

read_customers とあるが、上のチュートリアルや PM の紹介記事では、 read_customer_payment_methods というスコープが明記されている。なので、実際はこのアクセススコープが必要になる可能性が高い。

申請しないと 400 エラーが出る

Subscription APIs 関連のアクセススコープ（例えば、read_own_subscription_contracts）を申請せずにアプリのスコープに含めると、承認フローに入る前に 400 エラーが出る。

400 エラー

Oauth error missing_shopify_permission: read_own_subscription_contracts

Keisuke Inaba

アクセススコープの申請

前述のとおり、Partner Dashboard の「App setup > Subscriptions」から申請する。

App setup > Subscriptions

申請するとレビュー中に更新され、Shopify Support からも自動メールがくる。"This may take up to 7 business days." とあるので、早めに申請しておいた方がよいと思われる。

レビュー中

承認されるとメールで連絡くる。1月27日 (水) に申請して、1月29日 (金) に承認された。

承認後

read_own_subscription_contracts の権限をお願いしたが、なぜか read_customer_payment_methods と write_own_subscription_contracts の許可が下りた。

Keisuke Inaba

Subscription APIs のスコープについて

例えば、SubscriptionContract だと次のアクセススコープが要求される。

Requires either all_subscription_contracts or own_subscription_contracts scope.

サードパーティが作成したデータは取得できない？

PayWhirl でサブスクリプションをテスト購入し、 read_own_subscription_contracts 権限で Graphql の subscriptionContracts を叩いてみたが、 edges が空で返ってくる。クエリは次の通り。

<<-'GRAPHQL'
  query { 
    subscriptionContracts(first: 10) {
      edges {
        cursor
        node {
          id
          status
        }
      }
    }
  }
GRAPHQL

PayWhirl は Shopify Subscription APIs を利用しており（サポートに確認済み）、アプリ内でもサブスクリプションを確認できるので、スコープ権限の問題ではないかと考えられる。
read_own_subscription_contracts ではサードパーティが作成したサブスクリプションを取得できないと考えられる。ドキュメントに記載のある、 read_all_subscription_contracts ならいけそう。

Keisuke Inaba

Answer

Shopify Partner Support Specialist に質問したが

At this time, the access scope for read_all_subscription_contracts is only available to apps developed by Shopify.

read_all_subscription_contracts の権限は、現段階では Shopify が作ったアプリのみでしか利用できないとのこと。

よって現状は、サードパーティが作成したサブスクリプションデータを API 経由で取得できない。