Updated docs: new behavior -> standard behavior (#7258)

discord · Nov 5, 2024 · b70346a · b70346a
1 parent 55b4945
commit b70346a
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 32 deletions.
diff --git a/docs/change_log/2024-11-05-post-entitlement-migration-update.md b/docs/change_log/2024-11-05-post-entitlement-migration-update.md
@@ -0,0 +1,17 @@
+---
+title: "Entitlement Migration Completed"
+date: "2024-11-05"
+topics:
+- "Premium Apps"
+---
+
+The [entitlement migration](#DOCS_CHANGE_LOG/premium-apps-entitlement-migration-and-new-subscription-api) which began on **October 1, 2024**, has been successfully completed as of **November 1, 2024**.
+
+### What's Changed
+
+- The documentation has been updated to reflect the new entitlement system as the standard behavior.
+- `ENTITLEMENT_UPDATE` event for subscription-related entitlements now only occur when the subscription ends.
+- The `ends_at` value on the [entitlement object](#DOCS_RESOURCES_ENTITLEMENT/entitlement-object) is now set when the subscription ends.
+- To determine when a subscription was canceled, listen for `SUBSCRIPTION_UPDATE` events or use the [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) to retrieve the subscription's `status` and `canceled_at` timestamp.
+
+For more details about the migration process, please refer to the [migration guide](#DOCS_CHANGE_LOG/updates-to-entitlement-migration-guide).
diff --git a/docs/events/Gateway_Events.mdx b/docs/events/Gateway_Events.mdx
@@ -587,18 +587,19 @@ Sent when a message is pinned or unpinned in a text channel. This is not sent wh
 
 #### Entitlement Create
 
+> warn
+>  Note: The`ENTITLEMENT_CREATE` event behavior changed on October 1, 2024. Please see the [Change Log and Entitlement Migration Guide](#DOCS_CHANGE_LOG/premium-apps-entitlement-migration-and-new-subscription-api) for more information on what changed.
+
 Sent when an entitlement is created. The inner payload is an [entitlement](#DOCS_RESOURCES_ENTITLEMENT/entitlement-object) object.
 
 #### Entitlement Update
 
-> danger
-> Starting on October 1, 2024, the `ENTITLEMENT_UPDATE` event behavior will be changing. You will no longer receive an `ENTITLEMENT_UPDATE` event on successful renewal When a user cancels, you will receive an `ENTITLEMENT_UPDATE` events with an `ends_at` value when the subscription ends. See the [Change Log and Entitlement Migration Guide](#DOCS_CHANGE_LOG/premium-apps-entitlement-migration-and-new-subscription-api) for more information.
+> warn
+>  Note: The`ENTITLEMENT_UPDATE` event behavior changed on October 1, 2024. Please see the [Change Log and Entitlement Migration Guide](#DOCS_CHANGE_LOG/premium-apps-entitlement-migration-and-new-subscription-api) for more information on what changed.
 
 Sent when an entitlement is updated. The inner payload is an [entitlement](#DOCS_RESOURCES_ENTITLEMENT/entitlement-object) object. 
 
-For subscription entitlements, when a user's subscription is renewed you will receive an `ENTITLEMENT_UPDATE` event with a new `ends_at` date that reflects the end of the new billing period.
-
-If a user cancels their subscription, you will stop receiving `ENTITLEMENT_UPDATE` events that update the `ends_at` value.
+For subscription entitlements, this event is triggered only when a user's subscription ends, providing an `ends_at` timestamp that indicates the end of the entitlement.
 
 #### Entitlement Delete
 

diff --git a/docs/monetization/Implementing_App_Subscriptions.mdx b/docs/monetization/Implementing_App_Subscriptions.mdx
@@ -18,18 +18,6 @@ When creating subscriptions, you will need to choose between user or guild subsc
 
 ## How App Subscriptions Work
 
-> danger
-> **Starting on October 1st, 2024**, the`ENTITLEMENT_CREATE` and `ENTITLEMENT_UPDATE` event behavior described below is changing. Please see the [Change Log and Entitlement Migration Guide](#DOCS_CHANGE_LOG/premium-apps-entitlement-migration-and-new-subscription-api) for more information on what is changing and how to prepare.
-
-- When a user purchases your subscription SKU, Discord creates an [Entitlement](#DOCS_RESOURCES_ENTITLEMENT) for the user (or guild) and that specific Subscription [SKU](#DOCS_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 and updated with a new `ends_at` date for each succesful billing interval until the user decides to cancel their subscription.
-- When a user cancels their subscription, you will **not** receive an `ENTITLEMENT_UPDATE` with a new `ends_at` value, the entitlement will just expire at the current `ends_at` value.
-
-<Collapsible title="How App Subscriptions Work - Starting October 1st, 2024" icon="warning">
 - When a user purchases your subscription SKU, Discord creates an [Entitlement](#DOCS_RESOURCES_ENTITLEMENT) for the user (or guild) and that specific Subscription [SKU](#DOCS_RESOURCES_SKU). 
 - You will receive an `ENTITLEMENT_CREATE` event via the Gateway.
 - This entitlement will be available via the `LIST Entitlements` API endpoint.
@@ -39,8 +27,6 @@ When creating subscriptions, you will need to choose between user or guild subsc
 - 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.
 
- Please see the [Change Log and Entitlement Migration Guide](#DOCS_CHANGE_LOG/premium-apps-entitlement-migration-and-new-subscription-api) for more information on what is changing and how to prepare.
-
 ### 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.
@@ -57,32 +43,24 @@ Because entitlements are granted indefinitely and don't update on renewal or can
 | `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)`                                                                                                      |
 
-> info
-> These docs will be incorporated into the main documentation on November 1, 2024.
-
-</Collapsible>
-
 ---
 
 ## Working with Entitlements
 
-When a user purchases a subscription, an entitlement is created. [Entitlements](#DOCS_RESOURCES_ENTITLEMENT) represent the user's access to your consumable or durable item.
+When a user purchases a subscription, an entitlement is created. [Entitlements](#DOCS_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](#DOCS_EVENTS_GATEWAY_EVENTS/entitlements), the [Entitlement HTTP API](#DOCS_RESOURCES_ENTITLEMENT), and [interaction payloads](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING) to keep track of user and guild entitlements and grant perks to users who have subscribed to your app.
+Depending on your app's features, you can use a combination of [Gateway events](#DOCS_EVENTS_GATEWAY_EVENTS/entitlements), the [Entitlement HTTP API](#DOCS_RESOURCES_ENTITLEMENT), and [interaction payloads](#DOCS_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
 
-> danger
-> **Starting on October 1, 2024**, the `ENTITLEMENT_CREATE` and `ENTITLEMENT_UPDATE` event behavior described below is changing. Please see the [Change Log and Entitlement Migration Guide](#DOCS_CHANGE_LOG/premium-apps-entitlement-migration-and-new-subscription-api) for more information on what is changing and how to prepare. The docs will be updated on November 1, 2024 to reflect the new behavior.
-
-When users subscribe or renew a subscription with your app, Discord will emit [Entitlement Gateway events](#DOCS_EVENTS_GATEWAY_EVENTS/entitlements).
+When users make a purchase in your app, Discord will emit [Entitlement Gateway events](#DOCS_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 a subscription is resumed, renewed, or canceled                                                                                                               |
+| `ENTITLEMENT_UPDATE` | When a subscription ends                                                                                                                                           |
 | `ENTITLEMENT_DELETE` | When Discord refunds a subscription, removes an entitlement, or when a developer [deletes a Test Entitlement](#DOCS_RESOURCES_ENTITLEMENT/delete-test-entitlement) |
 
 ### Accessing Entitlements with the HTTP API
@@ -143,7 +121,7 @@ This method will not let you test out the full payment flow in Discord but will
 
 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](#DOCS_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 that includes a `starts_at` and `ends_at` value. If you cancel this subscription, it will remain an active entitlement until the `ends_at` timestamp. This subscription will renew until canceled and can be used in testing subscription renewals in your app.
+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](#DOCS_RESOURCES_SUBSCRIPTION/subscription-object). 
 
 > info
 > You can only delete entitlements created using the [create entitlement](#DOCS_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.