> ## Documentation Index
> Fetch the complete documentation index at: https://discord-platform-username.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/developers/monetization/enabling-monetization) for your app.
* Once you've confirmed eligibility for your app and team, you will be able to set up a [SKU](/developers/resources/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](/developers/resources/entitlement) for the user (or guild) and that specific Subscription [SKU](/developers/resources/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](/developers/resources/entitlement) 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](/developers/events/gateway-events#entitlements), the [Entitlement HTTP API](/developers/resources/entitlement), and [interaction payloads](/developers/interactions/receiving-and-responding) 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](/developers/events/gateway-events#entitlements).
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](/developers/resources/entitlement#delete-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](/developers/resources/entitlement#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](/developers/interactions/receiving-and-responding). 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](/developers/developer-tools/embedded-app-sdk) to build an [Activity](/developers/activities/overview), you can also [access a user's entitlements](/developers/developer-tools/embedded-app-sdk#getentitlements). Check out the [Implementing In-App Purchases for Activities](/developers/monetization/implementing-iap-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](/developers/monetization/managing-skus#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](/developers/components/reference#button) with a [premium style](/developers/components/reference#button-button-styles) 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](/developers/developer-tools/embedded-app-sdk) to build an [Activity](/developers/activities/overview), you can also launch the purchase flow for a specific SKU using the SDK. Check out the [Implementing In-App Purchases for Activities](/developers/monetization/implementing-iap-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](/developers/monetization/managing-skus#viewing-your-store-page) page. You can link directly to your Store page using our [Application Directory Store URL scheme](/developers/monetization/managing-skus#linking-to-your-store).
***
## Supporting Subscriptions
To support subscriptions in your app, you need to [create a subscription SKU](/developers/monetization/managing-skus#creating-a-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 |
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)` |
### 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](/developers/monetization/managing-skus#viewing-your-store-page) or their App Subscription settings.
To create multiple subscription tiers, you will need to [create multiple subscription SKUs](/developers/monetization/managing-skus#creating-a-sku) 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` |
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](/developers/resources/entitlement) 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](/developers/resources/subscription) 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](/developers/resources/subscription#list-sku-subscriptions): List all subscriptions for a specific SKU in your app.
* [Get SKU Subscription](/developers/resources/subscription#get-sku-subscription): Get a specific subscription in your app.
* [Subscription Gateway events](/developers/events/gateway-events#subscriptions): 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](/developers/resources/entitlement#create-test-entitlement) and [deleting](/developers/resources/entitlement#delete-test-entitlement) 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](/developers/monetization/implementing-app-subscriptions#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](/developers/monetization/implementing-app-subscriptions#prompting-users-to-subscribe). 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](/developers/resources/subscription#subscription-object).
You can only delete entitlements created using the [create entitlement](/developers/resources/entitlement#create-test-entitlement) endpoint. If you need to toggle access to your premium features during your development process, it is best to use Test Entitlements.