entitlement migration guide updates (discord#7201)

colinloretz · web-flow · commit a9cd2277d951 · 2024-10-07T15:07:39.000-07:00
Updates to entitlement migration guide
diff --git a/docs/change_log/2024-08-28-subscription-api-and-entitlement-migration.md b/docs/change_log/2024-08-28-subscription-api-and-entitlement-migration.md
@@ -6,14 +6,17 @@ topics:
 breaking: true
 ---
 
+> info
+> Updates to this Change Log entry was published on **October 7, 2024** to reflect up-to-date information. See the [new Change Log entry](#DOCS_CHANGE_LOG/updates-to-entitlement-migration-guide) for details on updates.
+
 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.
+- `ENTITLEMENT_UPDATE` events will occur only when a subscription ends, 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:
@@ -56,7 +59,7 @@ Post-migration, entitlements for Subscription SKUs purchased through Discord wil
 ### Migration Timeline
 
 - **Migration Start Date:** October 1, 2024
-- **Migration End Date:** October 31, 2024
+- **Migration End Date:** November 1, 2024
 
 ### Migration Impacts
 
@@ -65,7 +68,8 @@ Post-migration, entitlements for Subscription SKUs purchased through Discord wil
 - **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.
+    - No further events will be generated until the entitlement ends, which will then trigger an `ENTITLEMENT_UPDATE` event.
+    - The `ends_at` value in the `ENTITLEMENT_UPDATE` event and in the Entitlement API will indicate the timestamp when the entitlement ends.
 
 ### 2) Existing Entitlements Set to End
 
@@ -79,12 +83,12 @@ Post-migration, entitlements for Subscription SKUs purchased through Discord wil
     - 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.
+    - Monitor for `ENTITLEMENT_CREATE`, `ENTITLEMENT_UPDATE`, `SUBSCRIPTION_CREATE`, and `SUBSCRIPTION_UPDATE` events.
+    - Update any references to an entitlement `ends_at` timestamps, which now indicate the ending of an entitlement. If you need to know when a subscription's period ends, use the [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) and related [Subscription Gateway Events](#DOCS_TOPICS_GATEWAY_EVENTS/subscriptions).
 
 <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.
+- If the subscription renews successfully, you will receive an `ENTITLEMENT_CREATE` 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>
diff --git a/docs/change_log/2024-10-04-updates-to-entitlement-migration-guide.md b/docs/change_log/2024-10-04-updates-to-entitlement-migration-guide.md
@@ -0,0 +1,20 @@
+---
+title: "Updates to Entitlement Migration Guide"
+date: "2024-10-07"
+topics:
+- "Premium Apps"
+---
+
+The entitlement migration started on **October 1, 2024** and will continue through 11:59PM PST on **November 1, 2024**.
+
+We updated our previous entitlement migration guide to provide more up-to-date information on impacts of developer impacts. Here's a summary of the changes we made:
+
+- The migration will run through November 1, 2024 to ensure that any entitlements that are set to renew in October will be properly migrated to the new entitlement system upon renewal.
+- `ENTITLEMENT_UPDATE` events will only occur when a subscription ends. 
+- The value of the `ends_at` in `ENTITLEMENT_UPDATE` events indicate the timestamp for **when the entitlement is no longer valid**.
+- The `ends_at` value on the [entitlement object](#DOCS_RESOURCES_ENTITLEMENT/entitlement-object) is set when the subscription ends.
+- To receive the value of when a subscription was canceled, you should listen for the `SUBSCRIPTION_UPDATE` events or use the [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION).
+
+View the [updated migration guide](#DOCS_CHANGE_LOG/subscription-api-and-entitlement-migration).
+
+To see a full diff of the changes, refer to this pull request: [Entitlement Migration Guide Updates](https://github.com/discord/discord-api-docs/pull/7201).
diff --git a/docs/monetization/Implementing_App_Subscriptions.mdx b/docs/monetization/Implementing_App_Subscriptions.mdx
@@ -19,7 +19,7 @@ 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 is changing. Please see the [Change Log and Entitlement Migration Guide](#DOCS_CHANGE_LOG/subscription-api-and-entitlement-migration) for more information on what is changing and how to prepare.
+> **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/subscription-api-and-entitlement-migration) 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.
@@ -36,10 +36,30 @@ When creating subscriptions, you will need to choose between user or guild subsc
 - 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, you will receive an `ENTITLEMENT_UPDATE` event with an `ends_at` timestamp representing when the subscription ends and when related premium functionality should be revoked.
-- If the user changes their mind and reactivates their subscription, you will receive another `ENTITLEMENT_UPDATE` event setting the `ends_at` timestamp to 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.
 
  Please see the [Change Log and Entitlement Migration Guide](#DOCS_CHANGE_LOG/subscription-api-and-entitlement-migration) 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.
+
+> info
+> 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 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)`                                                                                                      |
+
+> info
+> These docs will be incorporated into the main documentation on November 1, 2024.
+
 </Collapsible>
 
 ---
@@ -53,15 +73,17 @@ Depending on your app's features, you can use a combination of [Gateway events](
 ### Accessing Entitlements with Gateway Events
 
 > danger
-> **Starting on October 1st, 2024**, the `ENTITLEMENT_CREATE` and `ENTITLEMENT_UPDATE` event behavior is changing. Please see the [Change Log and Entitlement Migration Guide](#DOCS_CHANGE_LOG/subscription-api-and-entitlement-migration) for more information on what is changing and how to prepare.
+> **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/subscription-api-and-entitlement-migration) 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_TOPICS_GATEWAY_EVENTS/entitlements).
 
-For subscription SKUs, you will receive the following events:
+For subscription SKUs, you will receive the following entitlement events:
 
-- [`ENTITLEMENT_CREATE`](#DOCS_TOPICS_GATEWAY_EVENTS/entitlement-create): When a user subscribes to your app.
-- [`ENTITLEMENT_UPDATE`](#DOCS_TOPICS_GATEWAY_EVENTS/entitlement-update): When a user renews their subscription.
-- [`ENTITLEMENT_DELETE`](#DOCS_TOPICS_GATEWAY_EVENTS/entitlement-delete): When Discord refunds a subscription, removes an entitlement, or when a developer [deletes a Test Entitlement](#DOCS_RESOURCES_ENTITLEMENT/delete-test-entitlement).
+| 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_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
 
diff --git a/docs/topics/Gateway_Events.md b/docs/topics/Gateway_Events.md
@@ -591,7 +591,7 @@ Sent when an entitlement is created. The inner payload is an [entitlement](#DOCS
 #### Entitlement Update
 
 > danger
-> Starting on October 1st, 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 a valid `ends_at` value reflecting when their subscription ends. Please see the [Change Log and Entitlement Migration Guide](#DOCS_CHANGE_LOG/subscription-api-and-entitlement-migration) for more information.
+> 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/subscription-api-and-entitlement-migration) for more information.
 
 Sent when an entitlement is updated. The inner payload is an [entitlement](#DOCS_RESOURCES_ENTITLEMENT/entitlement-object) object. 
 
