Charge users for premium app functionality with a recurring user or guild subscription.
- Before you can add an app subscription to your app, you must Enable Monetization for your app.
- Once you've confirmed eligibility for your app and team, you will be able to set up a SKU (stock-keeping unit) to represent your subscription.
When creating subscriptions, you will need to choose between user or guild subscriptions:
- User Subscriptions: Offers premium features to an individual user across any server where your app installed.
- Guild Subscriptions: Provides premium benefits to all members within a specific server.
- When a user purchases your subscription SKU, Discord creates an Entitlement for the user (or guild) and that specific Subscription SKU.
- You will receive an
ENTITLEMENT_CREATEevent via the Gateway. - This entitlement will be available via the
LIST EntitlementsAPI endpoint. - This entitlement will be available on
Interaction Payloadsinitiated from the entitled user or users in a guild (for guild subscriptions). - This subscription will be available via the
LIST SubscriptionsAPI endpoint. - This entitlement is granted indefinitely until the user decides to cancel their subscription.
ends_atwill be null. - When a user cancels their subscription, your app will not receive any entitlement events.
- When a subscription ends, the entitlement to the subscription will end. Developers will receive an
ENTITLEMENT_UPDATEevent with anends_attimestamp indicating when the subscription ended.
Because entitlements are granted indefinitely and don't update on renewal or cancellation, you can use subscription events to track the lifecycle of a subscription.
info This is not a complete list of when events may occur. You should use the presence of an entitlement to determine if a user has access to your premium features. The Subscription API and related events are intended for reporting and lifecycle management purposes and should not be used as the source of truth of whether a user has access to your premium features.
| Event Name | Subscription Behavior | Updated Fields |
|---|---|---|
SUBSCRIPTION_CREATE |
Subscription is created | status is either 0 (active) if an entitlement has been granted or 1 (ending) if an entitlement has not yet been granted |
SUBSCRIPTION_UPDATE |
Subscription is granted an entitlement | status is 0 (active) |
SUBSCRIPTION_UPDATE |
Subscription is renewed | current_period_start, current_period_end timestamps updated |
SUBSCRIPTION_UPDATE |
Subscription is upgraded or downgraded | sku_ids, entitlement_ids, renewal_sku_ids may be updated |
SUBSCRIPTION_UPDATE |
Subscription is canceled | canceled_at timestamp updated, status is 1 (ending) |
SUBSCRIPTION_UPDATE |
Subscription ends | status is 2 (inactive), this event is processed asynchronously and will not be immediate |
SUBSCRIPTION_UPDATE |
Subscription is resumed/uncanceled by user | status is 0 (active) |
When a user purchases a subscription, an entitlement is created. Entitlements represent the user's access to your app's premium features.
Depending on your app's features, you can use a combination of Gateway events, the Entitlement HTTP API, and interaction payloads to keep track of user and guild entitlements and grant features to users who are subscribed to your app.
When users make a purchase in your app, Discord will emit Entitlement Gateway events.
For subscription SKUs, you will receive the following entitlement events:
| Event | Description |
|---|---|
ENTITLEMENT_CREATE |
When a user is granted an entitlement to your app's subscription SKU |
ENTITLEMENT_UPDATE |
When an entitlement to a subscription SKU ends |
ENTITLEMENT_DELETE |
When Discord refunds a subscription, removes an entitlement, or when a developer deletes a Test Entitlement |
For apps requiring background processing or not solely reliant on interactions, keeping track of entitlements is essential. You can utilize the List Entitlements endpoint to list active and expired entitlements. Your app can filter entitlements by a specific user or guild by using the ?user_id=XYZ or ?guild_id=XYZ query params.
For example, you might keep track of our entitlements in a database and check if a user still has access to a specific SKU before performing a cron job or other task.
Entitlements are also available on the Interaction Payload when a user interacts with your app. You can find the entitlements on the entitlements field of the Interaction Payload when receiving and responding to interactions. You can use this field to determine if the user or guild is subscribed to your app.
When using the Embedded App SDK to build an Activity, you can also access a user's entitlements. Check out the Implementing In-App Purchases for Activities guide to learn more about monetization with the Embedded App SDK.
Responding with a premium button gives you the ability to prompt users to subscribe to your app when they attempt to use a premium feature without a subscription.
You can do this by sending a message with a button with a premium style and a sku_id that allows the user to upgrade to your premium offering.
If you are using the Embedded App SDK to build an Activity, you can also launch the purchase flow for a specific SKU using the SDK. Check out the Implementing In-App Purchases for Activities guide to learn more about monetization with the Embedded App SDK.
Users can start, upgrade, or downgrade their subscription from your app's Store page. You can link directly to your Store page using our Application Directory Store URL scheme.
To support subscriptions in your app, you need to create a subscription SKU and handle the following scenarios:
When a user subscribes to a new subscription, you will receive the following events:
| Event | Event Trigger |
|---|---|
SUBSCRIPTION_CREATE |
when the subscription is initially created. status is 0 (active) if the entitlement has been granted or 1 (ending) if the entitlement has not yet been granted. |
ENTITLEMENT_CREATE |
when the user is granted an entitlement for the new subscription |
SUBSCRIPTION_UPDATE |
when the subscription is updated with the entitlement_ids, renewal_sku_ids, and status (0 (active)) |
Users can cancel their subscription at any time from their Subscription settings.
When a user cancels their subscription, you will receive the following events:
| Event | Event Trigger |
|---|---|
SUBSCRIPTION_UPDATE |
when the subscription is updated to end with a status of 1 (ending) and canceled_at is set to the timestamp the user canceled |
The user's subscription and entitlement are still valid until the subscription current_period_end is reached.
If the subscription is not resumed before the subscription current_period_end, it will end and you will receive the following events:
| Event | Event Trigger |
|---|---|
ENTITLEMENT_UPDATE |
when the current entitlement ends. ends_at gets updated with a timestamp |
SUBSCRIPTION_UPDATE |
when the subscription is updated with the status of 2 (inactive) |
Users can resume their subscription at any time before the current_period_end is reached in their Subscription settings.
When a user resumes their subscription, you will receive the following events:
| Event | Event Trigger |
|---|---|
SUBSCRIPTION_UPDATE |
when the subscription is set to continue with a status of 0 (active) and canceled_at is set to null |
If you offer multiple subscription tiers in your app, users can upgrade or downgrade their subscription at any time from your Store page or their App Subscription settings.
To create multiple subscription tiers, you will need to create multiple subscription SKUs and support the following scenarios in your app:
If an user is on a lower tier subscription and upgrades to subscription tier that is the same price or higher, the user is charged the difference in price between the two subscriptions and the subscription period resets at the time of upgrading.
When the subscription is upgraded, the current entitlement for the lower tier will end immediately and you will receive the following events:
| Event | Event Trigger |
|---|---|
ENTITLEMENT_UPDATE |
when the current entitlement ends. ends_at gets updated with a timestamp |
ENTITLEMENT_CREATE |
when a new entitlement is created for the upgrade subscription SKU |
SUBSCRIPTION_UPDATE |
when the subscription is updated with the new entitlement_ids, sku_ids, current_period_start, current_period_end |
If an user is on a higher tier subscription and downgrades to a lower tier subscription, the user is not charged immediately because the price is lower than what was already paid.
The user has already paid for their current plan until subscription.current_period_end so their current plan will be valid until then and you will receive the following event:
| Event | Event Trigger |
|---|---|
SUBSCRIPTION_UPDATE |
when the subscription is updated to reflect the renewal SKU ID in subscription.renewal_sku_ids |
Once the user's current subscription expires on subscription.current_period_end, you will receive the following events:
| Event | Event Trigger |
|---|---|
ENTITLEMENT_UPDATE |
when the current entitlement ends. ends_at gets updated with a timestamp |
ENTITLEMENT_CREATE |
when a new entitlement is created for the downgraded subscription SKU |
SUBSCRIPTION_UPDATE |
when the subscription is updated with the new entitlement_ids, sku_ids, current_period_start, current_period_end |
info When implementing monetization, Entitlements should be considered the source of truth for a user's access to a specific SKU. The Subscription API is intended for reporting and lifecycle management purposes that happen outside the flow of a user's interaction with your app.
You can use the Subscription API to check on the status of your app subscriptions. This API allows you to list subscriptions by user for reporting purposes and to check on the status of subscriptions without having to access entitlements directly.
- List SKU Subscriptions: List all subscriptions for a specific SKU in your app.
- Get SKU Subscription: Get a specific subscription in your app.
- Subscription Gateway events: Discord will emit gateway events when a subscription is created, updated, and very rarely, deleted.
You can test your implementation by creating and deleting test entitlements. These entitlements will allow you to test your premium offering in both a subscribed and unsubscribed state as a user or guild.
This method will not let you test out the full payment flow in Discord but will allow you to test your app's behavior when a user is subscribed or unsubscribed. See Using Live Entitlements if you'd like to see the full payment flow.
info Test Entitlements do not have a
starts_atorends_atfield as they are valid until they are deleted.
If you'd like to test the full payment flow for your app, you can do so by interacting with your Store page or a premium styled button. Any team members associated with your app will automatically see a 100% discount on the price of the subscription, allowing you to purchase without the use of live payment method.
After checkout, you will have a live subscription. This subscription will renew until canceled and can be used in testing subscription renewals in your app. If you cancel this subscription, it will remain an active entitlement until the end of the subscription billing period, represented by the period_ends_at field on the Subscription.
info You can only delete entitlements created using the create entitlement endpoint. If you need to toggle access to your premium features during your development process, it is best to use Test Entitlements.