Premium App Subscriptions: Testing guidance (#6548)

* Update to testing docs

* Changelog for testing entitlements

* bump date

* Clarify test entitlement deletion

* fix description for exclude_ended?

* Update docs/Change_Log.md

Co-authored-by: Jiralite <[email protected]>

---------

Co-authored-by: Jiralite <[email protected]>

Author: colinloretz

docs/Change_Log.md

@@ -1,5 +1,15 @@
 # Change Log
 
+## Premium App Subscriptions: New Ways for Testing App Subscriptions
+#### Nov 29, 2023
+
+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
+
+Read more about [Testing your App Subscriptions Implementation](#DOCS_MONETIZATION_APP_SUBSCRIPTIONS/testing-your-implementation) for details.
+
 ## Fix Message Edit Interaction Response Permissions
 #### Nov 1, 2023
 

docs/monetization/App_Subscriptions.md

@@ -49,7 +49,7 @@ 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.
+Each interaction payload includes an `entitlements` field containing an array of full [entitlement objects](#DOCS_MONETIZATION_ENTITLEMENTS/entitlement-object).
 
 You can use this field to determine if the user or guild is subscribed to your app.
 
@@ -74,11 +74,22 @@ For example, you might keep track of our entitlements in a database and check a
 
 ## Testing Your Implementation
 
+### Using Test Entitlements
+
 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
 > Test Entitlements do not have a `starts_at` or `ends_at` field as they are valid until they are deleted.
 
+### Testing Payment Flow with Live Entitlements
+
+If you'd like to test the full payment flow for your app, you can do so by interacting with the `Upgrade` button. 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 cancelled and can be used in testing subscription renewals in your app.
+
+> info
+> You can only delete entitlements created using the [create test entitlement](#DOCS_MONETIZATION_ENTITLEMENTS/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.
+
 ## Receiving Payouts
 
 Once an app has made its first $100 it will become eligible for payout. A review will be conducted and if everything looks good, your team will begin to receive payouts.

docs/monetization/Entitlements.md

@@ -58,7 +58,7 @@ Returns all entitlements for a given app, active and expired.
 | after?         | snowflake                         | Retrieve entitlements after this entitlement ID      |
 | limit?         | integer                           | Number of entitlements to return, 1-100, default 100 |
 | guild_id?      | snowflake                         | Guild ID to look up entitlements for                 |
-| exclude_ended? | boolean                           | Whether expired entitlements should be omitted       |
+| exclude_ended? | boolean                           | Whether or not ended entitlements should be omitted  |
 
 ```json
 [