Implementing App Subscriptions

Learn how to implement recurring user and guild subscriptions for premium functionality.

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 is 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 for 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 (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

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 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

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 (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

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

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 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

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

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.

---

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 current_period_end 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.