# エンタイトルメント 顧客へのプロダクト機能のアクセス権を付与または取り消すタイミングを決定します。 エンタイトルメントを使用すると、内部サービスの機能を Stripe プロダクトに割り当てることができます。機能を割り当てた後に Stripe は割り当ての選択内容に基づき、(顧客のサブスクリプションのステータスに従って) アクセスをプロビジョニングまたはデプロビジョニングするタイミングと、どの機能を対象とするかを通知します。 エンタイトルメントは以下に使用できます。 - コードベースを変更することなく、料金体系の立ち上げ、変更、実験を行う - 顧客への機能アクセスの付与、取り消し、管理 - 請求システムをシンプルにする ![](https://d37ugbyn3rpeym.cloudfront.net/videos/entitlements-demo.mp4) ## Before you begin このガイドは、Stripe の [Subscription](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md) と [Costomer](https://docs.stripe.com/invoicing/customer.md) のリソースをすでに使用していることを前提としています。 # ダッシュボード > This is a ダッシュボード for when dashboard-or-api is dashboard. View the full page at https://docs.stripe.com/billing/entitlements?dashboard-or-api=dashboard. ## 始める エンタイトルメントの使用を開始するには、以下のようにします。 - **機能を設定する**: ダッシュボードから Stripe Billing の各機能を作成します。次のような機能を含めることができます。 - API アクセス - AI アシスタント - プレミアムサポート - 高度なレポート - データ保持期間の延長 - **機能をプロダクトに追加する**: 機能を対応する Stripe プロダクトに関連付けます。1 つの機能を複数のプロダクトに追加できます。 - **機能を管理する**: ダッシュボードから各機能を編集またはアーカイブします。 ## 機能を設定する ダッシュボードで機能を作成するには、以下の手順を実行します。 1. ダッシュボードで[プロダクトカタログ](https://dashboard.stripe.com/products)に移動し、**機能**をクリックします。 1. **+ 機能を作成する**をクリックして、機能の名前と検索キーを入力します。必要に応じてメタデータを追加することもできます。 1. 検索キーは機能ごとに一意であるため、検索キーに関連付けられた機能をアーカイブしない限り、別の機能で再利用することはできません。 1. **機能を作成する**をクリックします。 ## プロダクトに機能を追加する ダッシュボードでプロダクトに機能を追加するには、以下の手順を実行します。 1. ダッシュボードの[機能](https://dashboard.stripe.com/features)タブで、追加する機能をクリックします。 1. **プロダクトに関連付ける**をクリックして、メニューからプロダクトを選択します。 1. **確定する**をクリックします。 顧客が商品に登録する際、顧客が資格を持つ機能を表示できます。そのためには、[顧客](https://dashboard.stripe.com/customers)ページに移動して、顧客を選択し、エンタイトルメントセクションを確認します。 > 既存のサブスクリプションでは、次回の請求期間の開始時に、プロダクト機能の変更に対する有効なエンタイトルメントが作成されます。 ## 機能を管理する ダッシュボードから機能を管理できます。 ### 機能を編集する 機能の名前を編集したり、メタデータを追加したりするには、[機能](https://dashboard.stripe.com/features)タブに移動して、オーバーフローメニュー (⋯) をクリックし、**機能を編集する**をクリックします。機能の作成後に、機能の検索キーを編集することはできません。 ### プロダクトから機能を削除する プロダクトから機能を削除するには、[機能](https://dashboard.stripe.com/features)タブに移動して対象の機能を選択します。次に、プロダクト名の横にあるオーバーフローメニュー (⋯) をクリックし、**プロダクトを削除する**をクリックします。 ### 機能をアーカイブする 機能をアーカイブするには、[機能](https://dashboard.stripe.com/features)タブに移動し、オーバーフローメニュー (⋯) をクリックして、**機能をアーカイブする**をクリックします。 機能をアーカイブする前に、次の点に注意してください。 - アーカイブされた機能を編集したり、新しいプロダクトに追加したりすることはできません。 - アーカイブされた機能でも、既存のプロダクトに関連付けられている場合はエンタイトルメントが作成されます。 - アーカイブされた機能の検索キーは再度使用できます。 - 機能のアーカイブを解除することはできません。 # API > This is a API for when dashboard-or-api is api. View the full page at https://docs.stripe.com/billing/entitlements?dashboard-or-api=api. ## 始める エンタイトルメントの使用を開始するには、以下のようにします。 - **機能を設定する**: [Feature API](https://docs.stripe.com/api/entitlements/feature/object.md) を使用して Stripe Billing の各機能を作成します。次のような機能を含めることができます。 - API アクセス - AI アシスタント - プレミアムサポート - 高度なレポート - データ保持期間の延長 - **機能をプロダクトに追加する**: 機能を対応する Stripe プロダクトに関連付けます。1 つの機能を複数のプロダクトに追加できます。 - **顧客の有効なエンタイトルメントの取得**: 顧客がプロダクトに登録すると、Stripe Billing は顧客にプロダクトの機能を利用する資格を付与します。[Active Entitlement Summary Webhook](https://docs.stripe.com/billing/entitlements.md#webhooks) をリッスンし、指定された顧客に [List Active Entitlements API](https://docs.stripe.com/api/entitlements/active-entitlement/list.md) を適用して、機能のプロビジョニングプロセスを実行します。 ![エンタイトルメントと、顧客およびプロダクトの機能との関係を示す図](https://b.stripecdn.com/docs-statics-srv/assets/entitlements-diagram.240f8f8017776fc513dd69f291daed0d.png) ## 機能を設定する 作成する各機能に、名前と一意の `lookup_key` を指定します。`lookup_key` は各機能に一意のものであるため、異なる機能間で再利用することはできません。 ```curl curl https://api.stripe.com/v1/entitlements/features \ -u "<>:" \ -d "name=My feature" \ -d lookup_key=myinternalfeaturecode ``` ## プロダクトに機能を追加する 1 つ以上の商品への機能の割り当て > 既存のサブスクリプションでは、次回の請求期間の開始時に、プロダクト機能の変更に対する有効なエンタイトルメントが作成されます。 ```curl curl https://api.stripe.com/v1/products/{{PRODUCT_ID}}/features \ -u "<>:" \ -d "entitlement_feature={{ENTITLEMENTSFEATURE_ID}}" ``` プロダクトに機能を追加するリクエストを送信すると、次のようなレスポンスを受信します。 ```json { "id": "{{PRODUCT_FEATURE_ID}}", "object": "product_feature", "entitlement_feature": { "id": "{{ENTITLEMENTS_FEATURE_ID}}", "object": "entitlements.feature", "name": "My feature", "lookup_key": "myinternalfeaturecode" } } ``` プロダクト機能のリストを通じて、プロダクトに関連付けられている機能をページごとに一覧表示します。 ```curl curl https://api.stripe.com/v1/products/{{PRODUCT_ID}}/features \ -u "<>:" ``` また、プロダクト機能の関連付けを削除して、特定のプロダクトから機能を削除します。 ```curl curl -X DELETE https://api.stripe.com/v1/products/{{PRODUCT_ID}}/features/{{PRODUCTFEATURE_ID}} \ -u "<>:" ``` ## 顧客の有効なエンタイトルメントを取得する 顧客のサブスクリプションのライフサイクル (有効化、アップグレード、ダウングレードなど) 中、Stripe はマッピングされた機能に基づいて顧客の利用資格を更新します。 顧客のサブスクリプションが最初に有効化されたときに、Stripe は顧客が登録した機能のエンタイトルメントを作成します。 顧客が機能の有効なサブスクリプションを維持している限り、有効なエンタイトルメントは保持されます。この機能を利用する資格があるすべてのユーザーに対して、システムでアクセス権を提供してください。 ### Webhook をリッスンしてアクセスを許可または取り消します 顧客のエンタイトルメントが、製品のサブスクリプション、アップグレード、ダウングレード、キャンセルによって変更されると、Stripe は`entitlements.active_entitlement_summary.updated` Webhook を起動します。このイベントを使用して、お客様のシステムでアクセスのプロビジョニングを実行します。 **アクセス権の付与**: 顧客が機能が添付された製品を含むサブスクリプションを購入すると、Stripe は `entitlements.active_entitlement_summary.updated` を起動します。イベントペイロードには、顧客の最新のエンタイトルメントサマリーがすべて含まれています。お客様のアプリケーションは、`entitlements.data` にリストされている機能に対応する機能またはサービスのいずれかを有効にする必要があります。 **アクセスの取り消し**: 顧客がサブスクリプションをキャンセルした場合、または支払いの失敗によりサブスクリプションが自動的にキャンセルされた場合、Stripe は `entitlements.active_entitlement_summary.updated` を再度起動します。この時点で、取り消された機能は `entitlements.data` に表示されなくなります。お客様のアプリケーションは、それに応じて関連する機能またはサービスを無効にする必要があります。 > #### サマリー Webhook で利用できる限定エンタイトルメント > > entitlement summary の `entitlements.data` 配列には、最大 10 個の entitlements が含まれます。顧客に 10 個を超える有効な entitlements がある場合は、ペイロードの `entitlements.url` フィールドを使用して、ページ分割された完全なリストを取得します。 | イベント | 説明 | | ------------------------------------------------- | ---------------------------------------------------------------- | | `entitlements.active_entitlement_summary.updated` | 顧客の有効なエンタイトルメントが変更されるたびに発生します。たとえば、サブスクリプションが作成、更新、キャンセルされた場合です。 | Webhook ペイロードの `data.object` は `entitlements.active_entitlement_summary` オブジェクトです。次に、2 つの機能を備えた製品をサブスクしたばかりの顧客のペイロードの例を示します: ```json { "id": "evt_1OcCWTLkdIwHu7ixbUwdUFui", "object": "event", "created": 1706111369, "data": { "object": { "object": "entitlements.active_entitlement_summary", "customer": "cus_ABC123customer", "entitlements": { "object": "list", "data": [ { "id": "ent_test_61QG5x2cU1GluFTYs41JqiESbLiX8C8O", "object": "entitlements.active_entitlement", "feature": "feat_test_61QGU1MWyFMSP9YBZ41ClCIKljWvsTgu", "livemode": false, "lookup_key": "premium-support" }, { "id": "ent_test_72RH6y3dV2HmvGUZt52KrjFTcMjY9D9P", "object": "entitlements.active_entitlement", "feature": "feat_test_72RHV2NXzGNTP0ZCA52DmDJLkmXwtUhv", "livemode": false, "lookup_key": "advanced-reporting" } ], "has_more": false, "url": "/v1/customer/cus_ABC123customer/entitlements" }, "livemode": false }, "previous_attributes": { "entitlements": { "data": [] } } }, "livemode": false, "pending_webhooks": 0, "request": { "id": null, "idempotency_key": null }, "type": "entitlements.active_entitlement_summary.updated" } ``` 顧客のサブスクがキャンセルされ、機能が取り消されると、Stripe は同じイベントを起動しますが、`entitlements.data` には取り消された機能が含まれなくなります: ```json { "id": "evt_1OcDYTLkdIwHu7ixcVxeVGvj", "object": "event", "created": 1706115012, "data": { "object": { "object": "entitlements.active_entitlement_summary", "customer": "cus_ABC123customer", "entitlements": { "object": "list", "data": [], "has_more": false, "url": "/v1/customer/cus_ABC123customer/entitlements" }, "livemode": false }, "previous_attributes": { "entitlements": { "data": [ { "id": "ent_test_61QG5x2cU1GluFTYs41JqiESbLiX8C8O", "object": "entitlements.active_entitlement", "feature": "feat_test_61QGU1MWyFMSP9YBZ41ClCIKljWvsTgu", "livemode": false, "lookup_key": "premium-support" }, { "id": "ent_test_72RH6y3dV2HmvGUZt52KrjFTcMjY9D9P", "object": "entitlements.active_entitlement", "feature": "feat_test_72RHV2NXzGNTP0ZCA52DmDJLkmXwtUhv", "livemode": false, "lookup_key": "advanced-reporting" } ] } } }, "livemode": false, "pending_webhooks": 0, "request": { "id": null, "idempotency_key": null }, "type": "entitlements.active_entitlement_summary.updated" } ``` ### 顧客のすべての有効なエンタイトルメントのリストを取得する 申し込みで Webhook を待たずに顧客の現在のエンタイトルメントをいつでも確認する必要がある場合は、[List Active Entitlements](https://docs.stripe.com/api/entitlements/active-entitlement/list.md) を使用して直接取得できます。これは、申し込みスタートアップ、オーソリチェック、または Webhook 配信失敗後の状態を照合するのに役立ちます。 ```curl curl -G https://api.stripe.com/v1/entitlements/active_entitlements \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" ``` レスポンスは、指定された顧客の `entitlements.active_entitlement` オブジェクトのページ分割リストを返します。各オブジェクトには、機能の作成時に定義した `lookup_key` が含まれ、お客様のアプリケーションでのアクセス制限に使用できます。たとえば、顧客が `premium-support` と `advanced-reporting` 機能を備えた製品の有効なサブスクリプションを持っている場合、レスポンスは次のようになります: ```json { "object": "list", "url": "/v1/entitlements/active_entitlements", "has_more": false, "data": [ { "id": "ent_test_61QG5x2cU1GluFTYs41JqiESbLiX8C8O", "object": "entitlements.active_entitlement", "feature": "feat_test_61QGU1MWyFMSP9YBZ41ClCIKljWvsTgu", "lookup_key": "premium-support", "livemode": false }, { "id": "ent_test_72RH6y3dV2HmvGUZt52KrjFTcMjY9D9P", "object": "entitlements.active_entitlement", "feature": "feat_test_72RHV2NXzGNTP0ZCA52DmDJLkmXwtUhv", "lookup_key": "advanced-reporting", "livemode": false } ] } ``` 顧客に有効なエンタイトルメントがない場合 (サブスクリプションがキャンセルされた場合など)、`dataタ` 配列は空です。 > #### 推奨事項 > > 迅速に解決するために、これらのエンタイトルメントを内部で保持することをお勧めします。 > サブスクリプションの料金、プラン、エンタイトルメントの変更は、法的な要件の対象になる場合があります。弁護士に相談して、お客様のビジネスに関する詳細なアドバイスを受けてください。