discord · colinloretz · Aug 28, 2024 · Jul 31, 2024 · Aug 19, 2024 · Aug 27, 2024
@@ -10,13 +10,13 @@ Starting today, eligible US-based developers can monetize their verified apps wi
 * Manage subscription SKUs in the Developer Portal
 * View monetization analytics in the Developer Portal
 * Team owners can setup and manage payouts in Developer Portal
-* New endpoints for working with [SKUs](#DOCS_MONETIZATION_SKUS) and [Entitlements](#DOCS_MONETIZATION_ENTITLEMENTS):
-  * [List SKUs](#DOCS_MONETIZATION_SKUS/list-skus) `GET /applications/<application.id>/skus`
-  * [List Entitlements](#DOCS_MONETIZATION_ENTITLEMENTS/list-entitlements) `GET /applications/<application.id>/entitlements`
-  * [Create Test Entitlement](#DOCS_MONETIZATION_ENTITLEMENTS/create-test-entitlement) `POST /applications/<application.id>/entitlements`
-  * [Delete Test Entitlement](#DOCS_MONETIZATION_ENTITLEMENTS/delete-test-entitlement)  `DELETE /applications/<application.id>/entitlements/<entitlement.id>`
-* [Gateway Events](#DOCS_MONETIZATION_ENTITLEMENTS/gateway-events) for working with entitlements: `ENTITLEMENT_CREATE`, `ENTITLEMENT_UPDATE`, `ENTITLEMENT_DELETE`
-* New [`PREMIUM_REQUIRED (10)` interaction response type](#DOCS_MONETIZATION_ENTITLEMENTS/premiumrequired-interaction-response) is available to prompt users to upgrade
-* New `entitlements` field, which is an array of [entitlement](#DOCS_MONETIZATION_ENTITLEMENTS/) objects, available in interaction data payloads when [receiving and responding to interactions](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-structure)
+* New endpoints for working with [SKUs](#DOCS_RESOURCES_SKU) and [Entitlements](#DOCS_RESOURCES_ENTITLEMENT):
+  * [List SKUs](#DOCS_RESOURCES_SKU/list-skus) `GET /applications/<application.id>/skus`
+  * [List Entitlements](#DOCS_RESOURCES_ENTITLEMENT/list-entitlements) `GET /applications/<application.id>/entitlements`
+  * [Create Test Entitlement](#DOCS_RESOURCES_ENTITLEMENT/create-test-entitlement) `POST /applications/<application.id>/entitlements`
+  * [Delete Test Entitlement](#DOCS_RESOURCES_ENTITLEMENT/delete-test-entitlement)  `DELETE /applications/<application.id>/entitlements/<entitlement.id>`
+* [Gateway Events](#DOCS_TOPICS_GATEWAY_EVENTS/entitlements) for working with entitlements: `ENTITLEMENT_CREATE`, `ENTITLEMENT_UPDATE`, `ENTITLEMENT_DELETE`
+* New [`PREMIUM_REQUIRED (10)` interaction response type](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-response-object-interaction-callback-type) is available to prompt users to upgrade
+* New `entitlements` field, which is an array of [entitlement](#DOCS_RESOURCES_ENTITLEMENT/) objects, available in interaction data payloads when [receiving and responding to interactions](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-structure)
 
 To learn more about eligibility details and how to enable monetization for your app, check out the [Monetization Overview](#DOCS_MONETIZATION_OVERVIEW).
@@ -8,6 +8,6 @@ topics:
 Following feedback on Premium App Subscriptions, we've made it easier for developers to test their app subscriptions. The goal is to provide you with flexibility during testing and prevent you from having to use live payment methods.
 
 * Team members will automatically receive a 100% discount on a subscription for your app, allowing you to test the end-to-end payment flow
-* Developers can create and delete [test entitlements](#DOCS_MONETIZATION_ENTITLEMENTS/create-test-entitlement) to toggle access to an application's premium features
+* Developers can create and delete [test entitlements](#DOCS_RESOURCES_ENTITLEMENT/create-test-entitlement) to toggle access to an application's premium features
 
-Read more about [Testing your App Subscriptions Implementation](#DOCS_MONETIZATION_APP_SUBSCRIPTIONS/testing-your-implementation) for details.
+Read more about [Testing your App Subscriptions Implementation](#DOCS_MONETIZATION_IMPLEMENTING_APP_SUBSCRIPTIONS/testing-your-app-subscription-implementation) for details.
@@ -10,7 +10,7 @@ Two new features are now available for Premium Apps: One-Time Purchases and Stor
 * **Durable Items**: A one-time purchase that is permanent and is not subject to either renewal or consumption, such as lifetime access to an app's premium features.
 * **Consumable Items**: A one-time, non-renewable purchase that provides access, such as a temporary power-up or boost in a game.
 
-Learn more about implementing [One-Time Purchases](#DOCS_MONETIZATION_ONE-TIME_PURCHASES).
+Learn more about [Implementing One-Time Purchases](#DOCS_MONETIZATION_IMPLEMENTING_ONE-TIME_PURCHASES).
 
 **A Store for Your Premium App**
 
@@ -22,7 +22,7 @@ To explore these features, eligibility details, and how to enable monetization f
 
 The following were added to our public Monetization documentation with this update:
 
-* New [SKU Object Types](#DOCS_MONETIZATION_SKUS/sku-object-sku-types)
-* New [Entitlement Object Types](#DOCS_MONETIZATION_ENTITLEMENTS/entitlement-object-entitlement-types)
-* [Consume an Entitlement](#DOCS_MONETIZATION_ENTITLEMENTS/consume-an-entitlement) API endpoint
-* `consumed` field on the [Entitlement](#DOCS_MONETIZATION_ENTITLEMENTS) resource
+* New [SKU Object Types](#DOCS_RESOURCES_SKU/sku-object-sku-types)
+* New [Entitlement Object Types](#DOCS_RESOURCES_ENTITLEMENT/entitlement-object-entitlement-types)
+* [Consume an Entitlement](#DOCS_RESOURCES_ENTITLEMENT/consume-an-entitlement) API endpoint
+* `consumed` field on the [Entitlement](#DOCS_RESOURCES_ENTITLEMENT) resource
@@ -5,7 +5,7 @@ date: "2024-06-17"
 
 **New Premium Button Style**
 
-Introduces a new `premium` [button style](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles) to be used with a `sku_id` which points to an active [SKU](#DOCS_MONETIZATION_SKUS/sku-object). This allows developers to customize their premium experience by returning specific subscription or one-time purchase products.
+Introduces a new `premium` [button style](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles) to be used with a `sku_id` which points to an active [SKU](#DOCS_RESOURCES_SKU/sku-object). This allows developers to customize their premium experience by returning specific subscription or one-time purchase products.
 
 Learn more about using [button components with interactions](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/buttons).
 
@@ -14,11 +14,11 @@ Learn more about using [button components with interactions](#DOCS_INTERACTIONS_
 
 The `PREMIUM_REQUIRED (10)` interaction response type is now deprecated in favor of using custom premium buttons. This will continue to function but may be eventually unsupported. It is recommended to migrate your bots to use the more flexible [premium button component](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles).
 
-Learn more about [gating features with premium interactions](#DOCS_MONETIZATION_APP_SUBSCRIPTIONS/gating-premium-interactions).
+Learn more about [gating features with premium interactions](#DOCS_MONETIZATION_IMPLEMENTING_APP_SUBSCRIPTIONS/prompting-users-to-subscribe).
 
 **Deep Linking URL Schemes for SKUs and Store**
 
 Introduces two new url schemes for linking directly to the Application Directory. When these links are used in chat, they are rendered as rich embeds that users can interact with to launch an app's store or open a SKU detail modal.
 
-* New [Store URL Scheme](#DOCS_MONETIZATION_MANAGING_YOUR_STORE/linking-to-your-store): `https://discord.com/application-directory/:appID/store`
-* New [SKU URL Scheme](#DOCS_MONETIZATION_SKUS/linking-to-your-skus): `https://discord.com/application-directory/:appID/store/:skuID`
+* New [Store URL Scheme](#DOCS_MONETIZATION_MANAGING_SKUS/linking-to-your-store): `https://discord.com/application-directory/:appID/store`
+* New [SKU URL Scheme](#DOCS_MONETIZATION_MANAGING_SKUS/linking-to-a-specific-sku): `https://discord.com/application-directory/:appID/store/:skuID`
@@ -0,0 +1,90 @@
+---
+title: "Premium Apps: Entitlement Migration and New Subscription API"
+date: "2024-08-28"
+topics:
+- "Premium Apps"
+breaking: true
+---
+
+We are migrating our entitlement system to a new behavior where entitlements will not end until explicitly canceled, representing a breaking change for subscription management. We are introducing a [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) and [Subscription Events](#DOCS_TOPICS_GATEWAY_EVENTS/subscriptions) to allow handling subscription-related events.
+
+> warn
+> This change will be rolled out to all existing applications that have entitlements for user and guild subscription SKUs, starting on October 1, 2024.
+
+#### Entitlement Migration Details
+- `ENTITLEMENT_CREATE` events will now be triggered with a null `ends_at` value for all ongoing subscriptions, indicating an indefinite entitlement.
+- `ENTITLEMENT_UPDATE` events will occur only when a subscription is canceled, with the `ends_at` value indicating the end date.
+- Discord-managed Subscription entitlements will have an `type` value of `PURCHASE` (type `1`) instead of `APPLICATION_SUBSCRIPTION` (type `8`).
+
+### Migration Plan & Guide:
+As of **October 1, 2024**, all existing entitlements that grant access to user-subscription and guild-subscription SKUs will automatically transfer to the new system on their renewal date. This means we will have a month-long migration window to allow all of your entitlements to migrate to the new system upon renewal.
+
+Developers are advised to update their systems to handle the new `ENTITLEMENT_CREATE` and `ENTITLEMENT_UPDATE` events according to the following migration guide before the rollout date to avoid service disruptions.
+
+### Introducing a New Subscription API
+With the new entitlement behavior, entitlements for subscription SKUs will no longer emit events at the start of a new subscription billing period. Instead, subscription lifecycle management can be handled through the new [Subscription API](#DOCS_MONETIZATION_IMPLEMENTING_APP_SUBSCRIPTIONS/using-the-subscription-api).
+Developers should refer to the [Subscription resource](#DOCS_RESOURCES_SUBSCRIPTION) for information on calling the Subscription API and responding to Subscription events. For in-depth implementation details, see our [Implementing App Subscriptions](#DOCS_MONETIZATION_IMPLEMENTING_APP_SUBSCRIPTIONS/using-the-subscription-api) guide. You can start using this API now.
+
+### Monetization Documentation Updates
+As part of these changes, we've updated the documentation for Premium Apps. 
+- Created a new [Enabling Monetization](#DOCS_MONETIZATION_ENABLING_MONETIZATION) page to cover setting up your team, managing payouts, and enabling monetization for your apps
+- Created a new [Managing SKUs](#DOCS_MONETIZATION_MANAGING_SKUS/creating-a-sku) page to document how to create, update, publish, and promote your SKUs
+- Moved and added [Entitlement](#DOCS_RESOURCES_ENTITLEMENT), [SKU](#DOCS_RESOURCES_SKU) and [Subscription](#DOCS_RESOURCES_SUBSCRIPTION) resources to the **Resources** section
+- Updated guides for [Implementing App Subscriptions](#DOCS_MONETIZATION_IMPLEMENTING_APP_SUBSCRIPTIONS) and [Implementing One-Time Purchases](#DOCS_MONETIZATION_IMPLEMENTING_ONE-TIME_PURCHASES)
+
+### Subscription Entitlement Migration Guide
+
+Starting on **October 1, 2024**, we will be migrating our existing entitlement system to a new behavior where **entitlements do not expire until explicitly canceled**. This migration guide outlines the changes and impacts of this migration on developers and guides how to manage these changes effectively.
+
+> warn
+> With this update, entitlements for subscription SKUs will no longer emit events when a new subscription billing period begins. If you need to know when a subscription has been renewed, use the new [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) and related [Subscription Gateway Events](#DOCS_TOPICS_GATEWAY_EVENTS/subscriptions).
+
+### Current System
+
+Currently, entitlements for Subscription SKUs purchased through Discord have:
+- An `ends_at` date that corresponds to the subscription interval. This date is updated at each billing cycle.
+- A entitlement `type` value of `APPLICATION_SUBSCRIPTION` (type `8`).
+- An `ENTITLEMENT_UPDATE` event is triggered at the start of each new subscription period.
+
+### New System
+
+Post-migration, entitlements for Subscription SKUs purchased through Discord will:
+-  No longer have an end date (`ends_at` will be `null`) until the user decides to cancel the subscription.
+-  Now have an entitlement `type` value of `PURCHASE` (type `1`).
+-  No `ENTITLEMENT_UPDATE` events will be triggered until the subscription is canceled.
+
+### Migration Timeline
+
+- **Migration Start Date:** October 1, 2024
+- **Migration End Date:** October 31, 2024
+
+### Migration Impacts
+
+### 1) Existing Entitlements Scheduled to Renew
+
+- **During Migration Window:**
+    - These will automatically transfer to the new system.
+    - A new `ENTITLEMENT_CREATE` event will be triggered to indicate the migration. This does not indicate a net new entitlement.
+    - No further events will be generated until cancellation, which will then trigger an `ENTITLEMENT_UPDATE` event.
+
+### 2) Existing Entitlements Set to End
+
+- **During Migration Window:**
+    - These entitlements will naturally expire and not renew under the new system.
+    - No new entitlement events will be generated for these cases.
+
+### Developer Actions
+- **Pre-Migration:**
+    - Review and understand the new entitlement event structure.
+    - Adjust your system to handle `ends_at` being null, which now indicates an indefinite entitlement.
+    - Adjust your system not to expect type `APPLICATION_SUBSCRIPTION` (type `8`) for Discord-managed subscription entitlements.
+- **Post-Migration:**
+    - Monitor for `ENTITLEMENT_CREATE` and `ENTITLEMENT_UPDATE` events.
+    - Update your handling of `ends_at` timestamps to manage cancellations effectively.
+
+<Collapsible title="Entitlement Migration Example Scenario" description="Step-by-step example of an entitlement upgrading to the new entitlement system" icon="view" open>
+- The Entitlement Migration begins on October 1, 2024
+- You have an existing user subscription that has an existing `ends_at` timestamp for October 10, 2024.
+- If the subscription renews successfully, you will receive an `ENTITLEMENT_UPDATE` event on October 10, 2024, with an `ends_at` value of null
+- If you receive an `ENTITLEMENT_UPDATE` event with an `ends_at` timestamp, the entitlement for this subscription is expected to end at the timestamp value unless you receive subsequent `ENTITLEMENT_UPDATE` events between the cancellation and the `ends_at` value.
+</Collapsible>
@@ -90,16 +90,16 @@ Buttons are interactive components that render in messages. They can be clicked
 
 ###### Button Structure
 
-| Field      | Type                                                | Description                                                                                                             |
-|------------|-----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
-| type       | integer                                             | `2` for a button                                                                                                        |
-| style      | integer                                             | A [button style](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles)                                     |
-| label?     | string                                              | Text that appears on the button; max 80 characters                                                                      |
-| emoji?     | partial [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) | `name`, `id`, and `animated`                                                                                            |
-| custom_id? | string                                              | Developer-defined identifier for the button; max 100 characters                                                         |
-| sku_id?    | snowflake                                           | Identifier for a purchasable [SKU](#DOCS_MONETIZATION_SKUS/sku-object), only available when using premium-style buttons |
-| url?       | string                                              | URL for link-style buttons                                                                                              |
-| disabled?  | boolean                                             | Whether the button is disabled (defaults to `false`)                                                                    |
+| Field      | Type                                                | Description                                                                                                         |
+|------------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
+| type       | integer                                             | `2` for a button                                                                                                    |
+| style      | integer                                             | A [button style](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles)                                 |
+| label?     | string                                              | Text that appears on the button; max 80 characters                                                                  |
+| emoji?     | partial [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) | `name`, `id`, and `animated`                                                                                        |
+| custom_id? | string                                              | Developer-defined identifier for the button; max 100 characters                                                     |
+| sku_id?    | snowflake                                           | Identifier for a purchasable [SKU](#DOCS_RESOURCES_SKU/sku-object), only available when using premium-style buttons |
+| url?       | string                                              | URL for link-style buttons                                                                                          |
+| disabled?  | boolean                                             | Whether the button is disabled (defaults to `false`)                                                                |
 
 Buttons come in a variety of styles to convey different types of actions. These styles also define what fields are valid for a button.