Implementing App Subscriptions
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
Section titled “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 is installed.
- Guild Subscriptions: Provides premium benefits to all members within a specific server.
How App Subscriptions Work
Section titled “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_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.
Using Subscription Events for the Subscription Lifecycle
Section titled “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.
| Event Name | Subscription Behavior | Updated Fields |
|---|---|---|
SUBSCRIPTION_CREATE |
Subscription is created | status is either 0 (active) if an entitlement has been granted or 1 (inactive) 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 2 (ending) |
SUBSCRIPTION_UPDATE |
Subscription ends | status is 1 (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
Section titled “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
Section titled “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
Section titled “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 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
Section titled “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
Section titled “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
Section titled “Prompting Users to Subscribe”Responding with a Premium Button
Section titled “Responding with a Premium Button”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
Section titled “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
Section titled “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
Section titled “Supporting Subscriptions”To support subscriptions in your app, you need to create a subscription SKU and handle the following scenarios:
Starting a new subscription
Section titled “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 (inactive) 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
Section titled “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 2 (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 1 (inactive) |
Resuming a cancelled subscription
Section titled “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
Section titled “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
Section titled “Upgrading an existing subscription”If a user is on a lower tier subscription and upgrades to a 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
Section titled “Downgrading an existing subscription”If a 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 |
Using the Subscription API
Section titled “Using the Subscription API”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.
Testing Your App Subscription Implementation
Section titled “Testing Your App Subscription Implementation”Using Test Entitlements
Section titled “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.
Using Live Entitlements
Section titled “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 current_period_end field on the Subscription.