Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Billing
OverviewAbout the Billing APIs
Subscriptions
    How subscriptions work
    Quickstart
    Use cases
    Build your integration
    Subscription features
    Entitlements
    Analytics
Invoicing
Usage-based billing
Quotes
Customer management
Billing with other products
Revenue recovery
Automations
Revenue recognition
Test your integration
Tax
Overview
Use Stripe tax
Manage compliance
Reporting
Overview
Select a report
Configure reports
Reports API
Reports for multiple accounts
Revenue recognition
Data
OverviewSchema
Custom reports
Data Pipeline
Data management
HomeRevenueSubscriptions

Entitlements

Determine when you can grant or revoke product feature access to customers.

Entitlements enable you to map the features of your internal service to Stripe products. After you map your features, Stripe notifies you about when to provision or de-provision access (according to your customer’s subscription status), and to what features, based on your mapping choices.

Use Entitlements to:

  • Launch, change, and experiment with your pricing without needing to change your codebase
  • Grant, revoke, and manage customer’s feature access
  • Simplify your billing integration

Stripe Billing Entitlements API demo

Before you begin

This guide assumes that you’re already using Stripe Subscriptions and Customer resources.

Get started

To get started with Entitlements:

  • Set up your features: Create each feature in Stripe Billing using the Feature API. Here are some examples of features you can include:
    • API access
    • AI assistant
    • Premium support
    • Advanced reporting
    • Extended data retention
  • Add your features to products: Attach Features to corresponding Stripe Products. You can add a single feature to multiple products.
  • Get customers’ active entitlements: When customers subscribe to your products, Stripe Billing entitles the customer to the product’s features. Listen to the Active Entitlement Summary webhook and use the List Active Entitlements API for a given customer to execute your feature provisioning process.
Diagram with Entitlements and its relationship with a Customer and Product's features

Set up your features

Provide a name and a unique lookup_key for each feature you create. Because the lookup_key is unique to each feature, you can’t reuse it across different features.

Command Line
cURL
curl https://api.stripe.com/v1/entitlements/features \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d name="My feature" \ -d lookup_key=myinternalfeaturecode

Add your features to products

Assign your feature to one or more products.

Note

Existing subscriptions will create active entitlements for any product feature changes at the start of the next billing period.

Command Line
cURL
curl https://api.stripe.com/v1/products/
{{PRODUCT_ID}}
/features
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d entitlement_feature=
{{ENTITLEMENTS_FEATURE_ID}}

After you submit a request to attach your feature to your product, you receive a response similar to the following:

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

List the features attached to a product by paging through the list of product features:

Command Line
cURL
curl https://api.stripe.com/v1/products/
{{PRODUCT_ID}}
/features
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

And remove a feature from a specific product by deleting the product feature attachment:

Command Line
cURL
curl -X DELETE https://api.stripe.com/v1/products/
{{PRODUCT_ID}}
/features/
{{PRODUCT_FEATURE_ID}}
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Get customers' active entitlements

During the lifecycle of a customer’s subscription, from activation, through upgrades, downgrades, and so on, Stripe updates the customer’s entitlements based on your mapped features.

When a customer’s subscription is first activated, Stripe creates entitlements for the features that they’re subscribed to.

As long as a customer maintains an active subscription for a feature, they retain an active entitlement. Make sure you provision access in your system for any users entitled to this feature.

Listen for webhook events

If your webhooks are enabled, we send the following webhook event to notify you when a customer’s entitlements change.

Limited entitlements available in summary webhook

The entitlement summary’s active_entitlements property only contains a maximum of 10 entitlements. We also provide a URL to retrieve the full, paginated list of the customer’s entitlements.

EventDescription
entitlements.active_entitlement_summary.updatedOccurs each time a customer’s active entitlements change.

Retrieve the list of all active entitlements for a customer

The list endpoint returns paginated view of a customer’s active entitlements.

Command Line
cURL
curl -G https://api.stripe.com/v1/entitlements/active_entitlements \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d customer=
{{CUSTOMER_ID}}

Recommendation

We recommend you persist these entitlements internally for faster resolution.

Note

Subscription pricing, plan, and entitlement changes might be subject to certain legal requirements. Consult your legal adviser for advice specific to your business.

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access programme.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc