1 はじめに
2 CustomerPortalとは
- 2.1 StripeDashboard上からの設定
- 2.2 API経由での設定
3 問題発生
4 何が起こったのか
5 結論
- 5.1 余談
6 まとめ

はじめに

こんにちは、サイオステクノロジーの佐藤陽です。
今回はStripeのCustomerPortalで使われるConfigurationの設定でハマった点を紹介します。

Configurationの値が勝手に変更されてる？！
API経由とStripeDashboardから設定したときの違いって何？

という思いのある方は是非最後までご覧ください。

CustomerPortalとは

Customer Portalに関しては、こちらをご覧ください。

このとても便利なCustomerPortalですが、表示する内容やユーザーの操作制限など、ある程度のカスタマイズが可能です。

カスタマイズ方法としては以下2つがあります。

StripeDashboard上からの設定
API経由での設定

StripeDashboard上からの設定

表示の設定に関しては、StripeDashboard上からGUIベースで行うことができます。

こちらは見ればわかるので説明不要かなと思います。

API経由での設定

これらの設定はStripeのAPI経由でも設定が可能です。

利用するAPIとしては以下の2つです。

CreatePortalSessionは、実際にCustomerPortalのセッションを作成し、アクセスする為のURLを取得するためのAPIです。
CreatePortalConfigurationは、CustomerPortalの設定テンプレートのようなものを作成するAPIです。

流れとしては

事前にCreatePortalConfigurationで、表示内容やユーザーの操作制限を設定したConfigurationを作成しておく
アプリ上でCustomerPortalSessionを作成する際に、パラメータにConfigurationを指定する

といった形になります。

なお、パラメータによってはConfigurationにもSessionにも含まれるものがあります。(例えば default_return_url など)
基本的にSessionに指定した場合はSessionの値が優先されますが、詳細はドキュメントを確認してください！

問題発生

さて、

CustomerPortalを完全に理解した！

と思っていたら、1つ問題が発生しました。

APIを経由して作成していたConfigurationの値が、知らぬ間に変更されていたのです。
UpdatePortalConfigurationAPIを叩いた記憶はありません。

そこでAPIのログを辿ってみると、確かにConfigurationの値が更新されていました。
ログを見ると、何故かDashboard上からの操作によってConfigurationの値が更新されていることがわかりました。

何が起こったのか

結論から言うと

StripeDashboard上からCustomerPortalの設定を行ったことで、
API経由で作成したConfigurationの値が更新されてしまっていました。

以下に詳細を述べていきたいと思います。

Default Configuration

まず、Default Configuration という概念についてお話します。

CreatePortalSessionのconfigurationのパラメータを見ると

The ID of an existing configuration to use for this session, describing its functionality and features. If not specified, the session uses the default configuration.

という記載があり、default configurationという概念があることが分かります。

自分の理解としては、このdefault configurationというのは「StripeDashboard上で設定したConfigurationの値である」と認識していました。

結論から言うと、この理解が若干誤っていました。

どうやら、default configurationというのはStripeアカウントにおいて一番最初に作られたConfigurationの事のようです。

検証1

真っ新なStripeアカウントを作成し、API経由でPortal Configurationを2つ(A,B)作成してみます。

以下のようなものを2回実行してみてください。

curl https://api.stripe.com/v1/billing_portal/configurations \
-u "your api key" \
-d "features[customer_update][allowed_updates][]"=email \
-d "features[customer_update][allowed_updates][]"=tax_id \
-d "features[customer_update][enabled]"=true \
-d "features[invoice_history][enabled]"=true \
--data-urlencode "business_profile[privacy_policy_url]"="https://example.com/privacy" \
--data-urlencode "business_profile[terms_of_service_url]"="https://example.com/terms"

次に、StripeDashboard上からConfigurationの設定を変更します。
設定画面へ行くと、上のAPI経由で作成したConfigurationの値が既に入力されている事が確認できます。

この後、StripeDashboard上からConfigurationの値を編集すると、API経由で一番最初に作成したConfiguration(=Aとします)の値が更新されていることも確認できます。
また、Bの値に関しては設定に影響が無いことも確認できました。

検証2

次に、変更されたAのConfigurationのactive設定をfalseにしてみたいと思います。

curl https://api.stripe.com/v1/billing_portal/configurations/bpc_1Nap7FFKJ9JA5A1A0m4tSU2n \
-u "your api key" \
-d "active"=false

すると、レスポンスとして、以下のものが得られました。

{
    "error": {
        "message": "You cannot set `active: false` on your default PortalConfiguration.",
        "request_log_url": "https://dashboard.stripe.com/test/logs/req_RkcY9Sm2cwdikm?t=1691019716",
        "type": "invalid_request_error"
    }
}

defaultPortalConfigurationはfalseにできないよ！
と言われていることから、このAがdefaultPortalConfigurationであることに間違いなさそうです。

(そもそもConfigurationのis_defaultのParameter見ればわかったのですが、それは後述します。)

検証3

最後に、真っ新なStripeアカウントを再度作成し、一度ListPortalConfigurationを叩いてみます。

curl -G https://api.stripe.com/v1/billing_portal/configurations \
-u "" \

レスポンスとしては以下のものが得られ、Configurationが存在していないことが分かります。

{
  "object": "list",
  "data": [],
  "has_more": false,
  "url": "/v1/billing_portal/configurations"
}

このあとStripeDashboard上からCustomerPortalを設定し、「変更を保存」のボタンを押します。

このタイミングで再度ListConfigurationを実行すると、新規で1件Configurationが生成されていることが確認できました。

{
  "object": "list",
  "data": [
    {
      "id": "bpc_1NaoUbCdoz2KwRrypRGaEI8a",
      "object": "billing_portal.configuration",
      "active": true,
      "application": null,
...(略)

結論

これまでの検証から、以下のことが分かりました。

StripeDashboard上から行うCustomerPortalの設定は、DefaultPortalConfigurationの値と連携している
DefaultPortalConfigurationとは、Stripeアカウント上で最初に作成されたConfigurationである
- API経由で作成しようが、StripeDashboard上で作成しようが関係ない
- そもそもStripeDashboard上で設定しても、結局はAPI経由で作成されるため同じ事である
Dashboard上の操作で予期せぬ変更が入らぬよう、どのConfigurationがDefaultであるかを意識しておく必要がある

余談

ここら辺まで書いて気付いたのですが、Configurationのパラメータとして is_defaultというものが定義済みでした。
これを見れば、どのConfigurationがDefaultであるかすぐ判断できますね。

Whether the configuration is the default. If true, this configuration can be managed in the Dashboard and portal sessions will use this configuration unless it is overriden when creating the session.

ただ、UpdateConfigurationAPIを見ても、このis_defaultを更新する手段はないようですし
やはり最初に作られたConfigurationがDefaultであるということは変わらないのかなと思います。