Merge branch 'main' into fix-interaction-callback-docs

owocado · web-flow · commit 6b34186b52e4 · 2024-10-17T00:33:32.000+05:30
diff --git a/docs/activities/Building_An_Activity.mdx b/docs/activities/Building_An_Activity.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_label: Building an Activity
+sidebar_label: Quickstart
 ---
 
 # Building Your First Activity in Discord
@@ -134,22 +134,6 @@ Details about installation contexts is in the [Application documentation](#DOCS_
 
 Click on **Installation** in the left sidebar, then under **Installation Contexts** make sure both "User Install" and "Guild Install" are selected. This will make sure users can launch our app's Activity across Discord servers, DMs, and Group DMs.
 
-### Enable Activities
-
-Next, we'll need to enable Activities for your app. On the left hand sidebar under **Activities**, click **Getting Started**.
-
-Review this page and press **Enable**.
-
-![Enabling Activities in Settings](activities/getting-started-activities.png)
-
-After enabling Activities, you'll see the different Activity-related pages in your app's settings under the **Activities** section. Across these pages, you'll be able to update information like supported platforms, upload assets, and configure Activity-specific settings. We'll come back to this section later in the guide to set up URL mappings.
-
-#### Default Entry Point Command
-
-When you enable Activities for your app, a [default Entry Point command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/default-entry-point-command) called "Launch" is automatically created. This [Entry Point command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/entry-point-commands) is the primary way for users to launch your Activity in Discord.
-
-By default, interactions with this command will result in Discord opening your Activity for the user and posting a message in the channel where it was launched from. However, if you prefer to handle the interactions in your app, you can update the [`handler` field](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/entry-point-handlers) or create your own. Additional details are in the Entry Point command [documentation](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/entry-point-commands) and [development guide](#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/setting-up-an-entry-point-command).
-
 ### Add a Redirect URI
 
 Next, we'll add a Redirect URI, which is where a user is typically redirected to after authorizing with your app when going through the standard OAuth flow. While setting up a Redirect URI is required, the Embedded App SDK automatically handles redirecting users back to your Activity when the RPC [`authorize` command](#DOCS_DEVELOPER_TOOLS_EMBEDDED_APP_SDK/authorize) is called.
@@ -187,7 +171,6 @@ Back in your app's settings, click on **OAuth2** on the sidebar:
 <Collapsible title="Step 2 Checkpoint" icon="list" open>
 
 By the end of Step 2, make sure you have:
-- Created a Discord app with Activities enabled
 - Set up a placeholder Redirect URI
 - Added your app's Client ID and Client Secret to your project's `.env` file.
 </Collapsible>
@@ -266,7 +249,7 @@ By the end of Step 3, make sure you have:
 
 ## Step 4: Running your app in Discord
 
-Let's ensure everything is wired up correctly, then run the Activity in Discord.
+Let's ensure everything is wired up correctly, enable activities via the dev portal, and then run the Activity in Discord.
 
 ### Run your app
 
@@ -322,6 +305,21 @@ Back in your app's settings, click on the **URL Mappings** page under **Activiti
 
 Read details about URL Mapping [in the development guide](#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/url-mapping).
 
+### Enable Activities
+
+Next, we'll need to enable Activities for your app. On the left hand sidebar under **Activities**, click **Settings**.
+
+Find the first checkbox, labeled `Enable Activities`. Turn it on 🎉
+
+![Enabling Activities in Settings](activities/enable-activities.png)
+
+#### Default Entry Point Command
+
+When you enable Activities for your app, a [default Entry Point command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/default-entry-point-command) called "Launch" is automatically created. This [Entry Point command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/entry-point-commands) is the primary way for users to launch your Activity in Discord.
+
+By default, interactions with this command will result in Discord opening your Activity for the user and posting a message in the channel where it was launched from. However, if you prefer to handle the interactions in your app, you can update the [`handler` field](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/entry-point-handlers) or create your own. Additional details are in the Entry Point command [documentation](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/entry-point-commands) and [development guide](#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/setting-up-an-entry-point-command).
+
+
 ### Running your Activity in Discord
 
 Now that we are pointing Discord to our locally running app, we can launch the Activity in Discord!
@@ -342,6 +340,7 @@ We're looking pretty good so far, but we haven't wired up any Discord functional
 By the end of Step 4, make sure you have:
 - Set up a public endpoint
 - Added an Activity URL Mapping in your app's settings
+- Enabled Activities for your app
 - Successfully launched your Activity in Discord
 </Collapsible>
 
diff --git a/docs/activities/Development_Guides.mdx b/docs/activities/Development_Guides.mdx
@@ -209,9 +209,6 @@ Because your application is "sandboxed", it will be unable to make network reque
 
 #### How to set a URL Mapping
 
-> preview
-> This is only possible once Activities are enabled on your application.
-
 To add or modify your application's URL mappings, click on `Activities -> URL Mappings` and set the prefix and target values for each mapping as needed.
 
 ![Configuring your URL Mapping](activities/url-mapping-tutorial.png)
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. 
 
diff --git a/images/activities/enable-activities.png b/images/activities/enable-activities.png
diff --git a/images/activities/getting-started-activities.png b/images/activities/getting-started-activities.png
