discord · colinloretz · Oct 26, 2023 · Oct 26, 2023 · Oct 27, 2023 · Oct 27, 2023
diff --git a/docs/Change_Log.md b/docs/Change_Log.md
@@ -1,5 +1,25 @@
 # Change Log
 
+## Premium App Subscriptions: Updated Guidance for Entitlements & Skus
+#### October 27, 2023
+
+Following feedback on Premium App Subscriptions, we're working on a better way for developers to test their app subscriptions. The goal is to provide an alternative to creating test entitlements or using live payment methods.
+
+In the meantime, we’re providing updated guidance around the `/entitlements` and `/skus` HTTP endpoints. 
+
+> warn
+> These endpoints will remain available until the new testing method is available. **We strongly advise against embedding them in long-term tooling or libraries as they will be removed in the future.** We will announce new guidance and developers documentation when new testing options are ready to be used. 
+
+Updated documentation for each endpoint now reflects this advice:
+
+- [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>`
+
+> info
+> For interactions requiring a subscription, always reference the `entitlements` field within the interaction payload to determine subscription status. You should not rely on fetching entitlements from the API or attempting to synchronize them with your database.
+
 ## Premium App Subscriptions Now Available in the EU and UK
 #### October 19, 2023
 

diff --git a/docs/monetization/App_Subscriptions.md b/docs/monetization/App_Subscriptions.md
@@ -49,13 +49,14 @@ return new JsonResponse({
 
 If someone is already subscribed, this command will show the upgrade prompt with a disabled upgrade button. In order to avoid this, your interaction handler should check to see if the user or guild has an active entitlement for your SKU.
 
-Each interaction payload includes an `entitlements` field containing an array of full entitlement objects that the guild or user currently has entitlement to.
+When a user purchases a subscription, an entitlement is created. [Entitlements](#DOCS_MONETIZATION_ENTITLEMENTS) represent the user's access to your premium offering.
 
-You can use this field to determine if the user or guild is subscribed to your app.
+Each interaction payload includes an `entitlements` field containing an array of full entitlement objects that the guild or user currently has entitlement to.
 
-### Keeping Track of Entitlements
+You can use this field to determine if the user is subscribed to your app.
-You can use this field to determine if the user is subscribed to your app.
+You can use this field to determine if the user or guild is subscribed to your app.
-You can use this field to determine if the user is subscribed to your app.
+You can use this field to determine if the user or guild is subscribed to your app.
 
-When a user purchases a subscription, an entitlement is created. [Entitlements](#DOCS_MONETIZATION_ENTITLEMENTS) represent the user's access to your premium offering. You can keep track of entitlements using Gateway Events and the HTTP API.
+> info
+> Always reference the `entitlements` field within the interaction payload to determine subscription status. You should not rely on fetching entitlements from the API or attempting to synchronize them with your database.
 
 #### Entitlement Gateway Events
 
@@ -66,14 +67,11 @@ Upon a user's purchase of a SKU, you'll receive an [`ENTITLEMENT_CREATE`](#DOCS_
 > info
 > An [`ENTITLEMENT_DELETE`](#DOCS_MONETIZATION_ENTITLEMENTS/deleted-entitlement) event only occurs when Discord refunds a subscription or removes an entitlement, not when an entitlement expires or is canceled.
 
-#### Entitlement HTTP Endpoints
-
-For apps requiring background processing or not solely reliant on interactions, keeping track of entitlements is essential. You can utilize the [List Entitlements](#DOCS_MONETIZATION_ENTITLEMENTS/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 a user's subscription status before performing a cron job or other task.
-
 ## Testing Your Implementation
 
+> danger
+> Please be aware that these testing endpoints are temporary. They may be used for interim testing but should not be implemented in long-term tooling or libraries. We're actively developing an improved method for testing your premium offering, as highlighted in our [guidance updates on Entitlements and SKUs](#).
+
 You can test your implementation by [creating](#DOCS_MONETIZATION_ENTITLEMENTS/create-test-entitlement) and [deleting](#DOCS_MONETIZATION_ENTITLEMENTS/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. 
 
 > info

diff --git a/docs/monetization/Entitlements.md b/docs/monetization/Entitlements.md
@@ -46,6 +46,9 @@ Entitlements in Discord represent that a user or guild has access to a premium o
 
 ## List Entitlements % GET /applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/entitlements
 
+> danger
+> Please be aware that this endpoint is temporary. It may be used for interim testing but it should not be implemented in long-term tooling or libraries. We're actively developing an improved method for testing your premium offering, as highlighted in our [guidance updates on Entitlements and SKUs](#DOCS_CHANGE_LOG/premium-app-subscriptions-updated-guidance-for-entitlements-skus).
+
 Returns all entitlements for a given app, active and expired.
 
 ###### Query Params
@@ -82,6 +85,9 @@ Returns all entitlements for a given app, active and expired.
 
 ## Create Test Entitlement % POST /applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/entitlements
 
+> danger
+> Please be aware that this endpoint is temporary. It may be used for interim testing but it should not be implemented in long-term tooling or libraries. We're actively developing an improved method for testing your premium offering, as highlighted in our [guidance updates on Entitlements and SKUs](#DOCS_CHANGE_LOG/premium-app-subscriptions-updated-guidance-for-entitlements-skus).
+
 Creates a test entitlement to a given SKU for a given guild or user. Discord will act as though that user or guild has entitlement to your premium offering.
 
 This endpoint returns a partial entitlement object. It will **not** contain `subscription_id`, `starts_at`, or `ends_at`, as it's valid in perpetuity.
@@ -106,6 +112,9 @@ After creating a test entitlement, you'll need to reload your Discord client. Af
 
 ## Delete Test Entitlement % DELETE /applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/entitlements/{entitlement.id#DOCS_MONETIZATION_ENTITLEMENTS/entitlement-object}
 
+> danger
+> Please be aware that this endpoint is temporary. It may be used for interim testing but it should not be implemented in long-term tooling or libraries. We're actively developing an improved method for testing your premium offering, as highlighted in our [guidance updates on Entitlements and SKUs](#DOCS_CHANGE_LOG/premium-app-subscriptions-updated-guidance-for-entitlements-skus).
+
 Deletes a currently-active test entitlement. Discord will act as though that user or guild _no longer has_ entitlement to your premium offering.
 
 Returns `204 No Content` on success.
@@ -181,4 +190,5 @@ return res.send({
 
 To check what the current guild or user has entitlements to, your app can inspect the `entitlements` field. `entitlements` is an array of [entitlement objects](#DOCS_MONETIZATION_ENTITLEMENTS/entitlement-object) for the current guild and user.
 
-You can reference `entitlements` during interactions to handle subscription status, rather than fetching entitlements from the API or your database.
+> info
+> Always reference the `entitlements` field within the interaction payload to determine subscription status. You should not rely on fetching entitlements from the API or attempting to synchronize them with your database.
diff --git a/docs/monetization/SKUs.md b/docs/monetization/SKUs.md
@@ -110,6 +110,9 @@ Congratulations on going live! 🥳
 
 ## List SKUs % GET /applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/skus
 
+> danger
+> Please be aware that this endpoint is temporary. It may be used for interim testing but it should not be implemented in long-term tooling or libraries. We're actively developing an improved method for testing your premium offering, as highlighted in our [guidance updates on Entitlements and SKUs](#DOCS_CHANGE_LOG/premium-app-subscriptions-updated-guidance-for-entitlements-skus).
+
 Returns all SKUs for a given application. Because of how our SKU and subscription systems work, you will see two SKUs for your premium offering. For integration and testing entitlements, you should use the SKU with `type: 5`.
 
 ```json