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.
Types of Subscriptions
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.
How App Subscriptions Work
- 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_CREATE event via the Gateway.
- This entitlement will be available via the
LIST Entitlements API endpoint.
- This entitlement will be available on
Interaction Payloads initiated from the entitled user or users in a guild (for guild subscriptions).
- This subscription will be available via the
LIST Subscriptions API endpoint.
- This entitlement is granted indefinitely until the user decides to cancel their subscription.
ends_at will 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_UPDATE event with an ends_at timestamp indicating when the subscription ended.
Using Subscription Events for the Subscription Lifecycle
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.
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) |
Working with Entitlements
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.
Accessing Entitlements with Gateway Events
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 |
Accessing Entitlements with the HTTP API
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.
Accessing Entitlements on Interaction Payloads
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.
Accessing Entitlements with the Embedded App SDK
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.
Prompting Users to Subscribe
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.
Starting a Purchase from an Activity
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.
Purchasing from the Store Page
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.
Supporting Subscriptions
To support subscriptions in your app, you need to create a subscription SKU and handle the following scenarios:
Starting a new subscription
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)) |
Cancelling an existing subscription
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 |
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) |
Resuming a cancelled subscription
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 |
Supporting Upgrades and Downgrades
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:
Upgrading an existing subscription
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 |
Downgrading an existing subscription
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 |
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 |
Using the Subscription API
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.
Testing Your App Subscription Implementation
Using Test Entitlements
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.
Test Entitlements do not have a starts_at or ends_at field as they are valid until they are deleted.
Using Live Entitlements
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.
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. 
