エンタイトルメント

顧客へのプロダクト機能のアクセス権を付与または取り消すタイミングを決定します。

エンタイトルメントを使用すると、内部サービスの機能を Stripe プロダクトに割り当てることができます。機能を割り当てた後に Stripe は割り当ての選択内容に基づき、(顧客のサブスクリプションのステータスに従って) アクセスをプロビジョニングまたはデプロビジョニングするタイミングと、どの機能を対象とするかを通知します。

エンタイトルメントは以下に使用できます。

コードベースを変更することなく、料金体系の立ち上げ、変更、実験を行う
顧客の機能アクセスの付与、取り消し、管理
請求システムをシンプルにする

Stripe Billing Entitlements API のデモ

はじめに

このガイドは、Stripe の Subscription と Costomer のリソースをすでに使用していることを前提としています。

始める

エンタイトルメントの使用を開始するには、以下のようにします。

機能を設定する: Feature API を使用して Stripe Billing の各機能を作成します。次のような機能を含めることができます。
- API アクセス
- AI アシスタント
- プレミアムサポート
- 高度なレポート
- データ保持期間の延長
機能をプロダクトに追加する: 機能を対応する Stripe プロダクトに関連付けます。1 つの機能を複数のプロダクトに追加できます。
顧客の有効なエンタイトルメントの取得: 顧客がプロダクトに登録すると、Stripe Billing は顧客にプロダクトの機能を利用する資格を付与します。Active Entitlement Summary Webhook をリッスンし、指定された顧客に List Active Entitlements API を適用して、機能のプロビジョニングプロセスを実行します。

機能を設定する

作成する各機能に、名前と一意の lookup_key を指定します。lookup_key は各機能に一意のものであるため、異なる機能間で再利用することはできません。

プロダクトに機能を追加する

1 つ以上の商品への機能の割り当て

注

既存のサブスクリプションでは、次回の請求期間の開始時に、プロダクト機能の変更に対する有効なエンタイトルメントが作成されます。

プロダクトに機能を追加するリクエストを送信すると、次のようなレスポンスを受信します。

{
  "id": "{{PRODUCT_FEATURE_ID}}",
  "object": "product_feature",
  "entitlement_feature": {
    "id": "{{ENTITLEMENTS_FEATURE_ID}}",
    "object": "entitlements.feature",
    "name": "My feature",
    "lookup_key": "myinternalfeaturecode"
  }
}

プロダクト機能のリストを通じて、プロダクトに関連付けられている機能をページごとに一覧表示します。

また、プロダクト機能の関連付けを削除して、特定のプロダクトから機能を削除します。

顧客の有効なエンタイトルメントを取得する

顧客のサブスクリプションのライフサイクル (有効化、アップグレード、ダウングレードなど) 中、Stripe はマッピングされた機能に基づいて顧客の利用資格を更新します。

顧客のサブスクリプションが最初に有効化されたときに、Stripe は顧客が登録した機能のエンタイトルメントを作成します。

顧客が機能の有効なサブスクリプションを維持している限り、有効なエンタイトルメントは保持されます。この機能を利用する資格があるすべてのユーザーに対して、システムでアクセス権を提供してください。

Webhook イベントのリッスン

Webhook が有効な場合、顧客のエンタイトルメントに変化があると、Stripe から以下の Webhook イベントを送信してお知らせします。

サマリー Webhook で利用できる限定エンタイトルメント

エンタイトルメントのサマリーの active_entitlements プロパティーには最大で 10 個までのエンタイトルメントのみが格納されます。Stripe は顧客のエンタイトルメントすべての一覧 (複数ページに分割) を取得するための URL も用意しています。

イベント	説明
`entitlements.active_entitlement_summary.updated`	顧客の有効なエンタイトルメントが変わるたびに発生します。

顧客のすべての有効なエンタイトルメントのリストを取得する

リストエンドポイントから、顧客の有効なエンタイトルメントが複数ページに分割されたビューが返されます。

推奨事項

迅速に解決するために、これらのエンタイトルメントを内部で保持することをお勧めします。

注

サブスクリプションの料金、プラン、エンタイトルメントの変更は、法的な要件の対象になる場合があります。弁護士に相談して、お客様のビジネスに関する詳細なアドバイスを受けてください。