PayPalサブスクリプションにおけるプラン変更実装の注意点

はじめに

株式会社ウェイブでCoolmicのエンジニアをしている布施です。
Coolmicは日本のコミックを海外向けに配信するWEBサービスです。

PayPalのサブスクリプション機能を実装するにあたり、APIの扱いでつまづいたところがあったので記事を書きました。

要約

• /v1/billing/subscriptions/{id}/reviseでは、同じproductに紐づくplanの間でしかプラン変更はできない

PayPalサブスクリプションに必要な準備

PayPalサブスクリプションを実装するにあたり、PayPal管理画面で以下のリソースをあらかじめ作成しておく必要があります。

• product: サブスクリプションにより提供される商品情報
• plan: サブスクリプションによりproductを提供するプラン

planを作成するときには必ず1つのproductを関連づけます。

プラン変更

同じproductのplanに変更する場合（通常のケース）

1. /v1/billing/subscriptions/{id}/reviseにPOSTリクエストを送る
2. レスポンスのlinksの中の"rel": "approve"の要素のhrefのURLにGETリクエストを送る（正常系のレスポンスサンプルはドキュメントを見てね）
3. ユーザーが遷移したPayPalのページでプラン変更を承認すれば、プラン変更完了

異なるproductのplanに変更しようとすると、reviseは下記のようなレスポンスを返します。

{
  "name": "UNPROCESSABLE_ENTITY",
  "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
  "debug_id": "xxxxxxxx",
  "details": [
    {
      "issue": "PLAN_PRODUCT_NOT_COMPATIBLE",
      "description": "The old and the new plans should be for the same product."
    }
  ],
  "links": [
    {
      "href": "https://developer.paypal.com/docs/api/v1/billing/subscriptions#UNPROCESSABLE_ENTITY",
      "rel": "information_link",
      "method": "GET"
    }
  ]
}

これを見て初めて、同じproductに紐づくplanの間でしかプラン変更はできないというルールを知り、productの扱いを間違えていたことに気づきました😇

異なるproductのplanに変更する場合

1. /v1/billing/subscriptions/#{id}/cancelにPOSTリクエストを送り、購読中のサブスクリプションをキャンセルする
2. /v1/billing/subscriptionsにPOSTリクエストを送り、新しいplanに対するサブスクリプションを作成する（start_timeパラメータをちょうどいい時間にしておく）
3. レスポンスのlinksの中の"rel": "approve"の要素のhrefのURLにGETリクエストを送る（正常系のレスポンスサンプルはドキュメントを見てね）
4. ユーザーが遷移したPayPalのページでサブスクリプション作成を承認すれば、新プラン作成完了。実質プラン変更完了

この方法でプラン変更をする場合、サブスクリプションのサイクル回数ほか必要な情報を、アプリ側のデータベースで管理しておく必要があります。

最後に

ドキュメントにはエラーケースのレスポンスサンプルが記載されていなかったので（私の確認不足の可能性は大いにある）、実際に検証してみて初めて気づくことがありました。
当たり前ですが、ドキュメントを読み込むことと実際に手を動かすことは両方大事ですね〜〜〜

参考

• Create subscription
• Revise plan or quantity of subscription
• Cancel subscription