Skip to content

Commit 5af3428

Browse files
colinloretzMisha-133
colinloretz
and
Misha-133
authored
premium apps: Support for multiple subscription tiers (discord#7304)
* support multiple subscription tiers * Update docs/resources/Subscription.md Co-authored-by: Mihail Gribkov <61027276+Misha-133@users.noreply.github.com> * update entitlement_ids and sku_ids * our beloved tables --------- Co-authored-by: Mihail Gribkov <61027276+Misha-133@users.noreply.github.com>
1 parent e70f3ce commit 5af3428

File tree

5 files changed

+144
-15
lines changed

5 files changed

+144
-15
lines changed

‎docs/change_log/2024-12-12-premium-apps-multiple-subscription-tiers.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "Premium Apps: Multiple Subscription Tiers"
3+
date: "2024-12-12"
4+
topics:
5+
- "Premium Apps"
6+
---
7+
8+
Developers with monetization enabled can now create and publish multiple subscription SKUs of the same type for their app. This allows developers to offer different subscription tiers with varying benefits and pricing. Users can upgrade and downgrade between published subscription SKUs.
9+
10+
### What's Changed
11+
12+
#### Developer Portal
13+
- Under the `Monetization` tab, you can now publish multiple subscription SKUs of the same type for your app.
14+
15+
#### App's Store Page
16+
- When multiple subscription SKUs are published: Users can now upgrade or downgrade between different published subscription SKUs.
17+
18+
#### User App Subscription Settings
19+
- When multiple subscription SKUs are published: Users can now upgrade or downgrade between different published subscription SKUs.
20+
- These settings are available under `User Settings → Subscriptions → App Subscriptions`.
21+
22+
#### Subscription Object
23+
- New field `renewal_sku_ids` added to the [subscription object](#DOCS_RESOURCES_SUBSCRIPTION/subscription-object) response for `SUBSCRIPTION_UPDATE` events and API endpoints.
24+
- `renewal_sku_ids` is a list of snowflakes that indicate the SKU(s) that the user will be subscribed to at renewal.
25+
26+
#### Updated Guide: Managing SKUs
27+
- The [Managing SKUs](#DOCS_MONETIZATION_MANAGING_SKUS/creating-a-sku) guide has been updated to include information about creating and managing multiple subscription SKUs.
28+
29+
#### Updated Guide: Implementing App Subscriptions
30+
- The [Implementing App Subscriptions](#DOCS_MONETIZATION_IMPLEMENTING_APP_SUBSCRIPTIONS/supporting-upgrades-and-downgrades) guide has been updated to include information about supporting upgrades and downgrades between multiple subscription SKUs.

‎docs/monetization/Implementing_App_Subscriptions.mdx

Lines changed: 91 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ Because entitlements are granted indefinitely and don't update on renewal or can
3939
| `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 |
4040
| `SUBSCRIPTION_UPDATE` | Subscription is granted an entitlement | `status` is `0 (active)` |
4141
| `SUBSCRIPTION_UPDATE` | Subscription is renewed | `current_period_start`, `current_period_end` timestamps updated |
42+
| `SUBSCRIPTION_UPDATE` | Subscription is upgraded or downgraded | `sku_ids`, `entitlement_ids`, `renewal_sku_ids` may be updated |
4243
| `SUBSCRIPTION_UPDATE` | Subscription is canceled | `canceled_at` timestamp updated, `status` is `1 (ending)` |
4344
| `SUBSCRIPTION_UPDATE` | Subscription ends | `status` is `2 (inactive)`, this event is processed asynchronously and will not be immediate |
4445
| `SUBSCRIPTION_UPDATE` | Subscription is resumed/uncanceled by user | `status` is `0 (active)` |
@@ -60,7 +61,7 @@ For subscription SKUs, you will receive the following entitlement events:
6061
| Event | Description |
6162
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
6263
| `ENTITLEMENT_CREATE` | When a user is granted an entitlement to your app's subscription SKU |
63-
| `ENTITLEMENT_UPDATE` | When a subscription ends |
64+
| `ENTITLEMENT_UPDATE` | When an entitlement to a subscription SKU ends |
6465
| `ENTITLEMENT_DELETE` | When Discord refunds a subscription, removes an entitlement, or when a developer [deletes a Test Entitlement](#DOCS_RESOURCES_ENTITLEMENT/delete-test-entitlement) |
6566

6667
### Accessing Entitlements with the HTTP API
@@ -91,14 +92,102 @@ You can do this by sending a message with a [button](#DOCS_INTERACTIONS_MESSAGE_
9192

9293
If you are using the [Embedded App SDK](#DOCS_DEVELOPER_TOOLS_EMBEDDED_APP_SDK) to build an [Activity](#DOCS_ACTIVITIES_OVERVIEW), you can also launch the purchase flow for a specific SKU using the SDK. Check out the [Implementing In-App Purchases for Activities](#DOCS_MONETIZATION_IMPLEMENTING_IAP_FOR_ACTIVITIES) guide to learn more about monetization with the Embedded App SDK.
9394

95+
### Purchasing from the Store Page
96+
97+
Users can start, upgrade, or downgrade their subscription from your app's [Store](#DOCS_MONETIZATION_MANAGING_SKUS/viewing-your-store-page) page. You can link directly to your Store page using our [Application Directory Store URL scheme](#DOCS_MONETIZATION_MANAGING_SKUS/linking-to-your-store).
98+
99+
---
100+
101+
## Supporting Subscriptions
102+
103+
To support subscriptions in your app, you need to [create a subscription SKU](#DOCS_MONETIZATION_MANAGING_SKUS/creating-a-sku) and handle the following scenarios:
104+
105+
### Starting a new subscription
106+
107+
When a user subscribes to a new subscription, you will receive the following events:
108+
109+
| Event | Event Trigger |
110+
|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
111+
| `SUBSCRIPTION_CREATE` | when the subscription is initially created. `status` is `0 (active)` if the entitlement has been granted or `1 (ending)` if the entitlement has not yet been granted. |
112+
| `ENTITLEMENT_CREATE` | when the user is granted an entitlement for the new subscription |
113+
| `SUBSCRIPTION_UPDATE` | when the subscription is updated with the `entitlement_ids`, `renewal_sku_ids`, and `status` (`0 (active)`) |
114+
115+
### Cancelling an existing subscription
116+
117+
Users can cancel their subscription at any time from their Subscription settings.
118+
119+
When a user cancels their subscription, you will receive the following events:
120+
121+
| Event | Event Trigger |
122+
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------|
123+
| `SUBSCRIPTION_UPDATE` | when the subscription is updated to end with a `status` of `1 (ending)` and `canceled_at` is set to the timestamp the user canceled |
124+
125+
The user's subscription and entitlement are still valid until the subscription `current_period_end` is reached.
126+
127+
If the subscription is not resumed before the subscription `current_period_end`, it will end and you will receive the following events:
128+
129+
| Event | Event Trigger |
130+
|-----------------------|----------------------------------------------------------------------------|
131+
| `ENTITLEMENT_UPDATE` | when the current entitlement ends. `ends_at` gets updated with a timestamp |
132+
| `SUBSCRIPTION_UPDATE` | when the subscription is updated with the `status` of `2 (inactive)` |
133+
134+
### Resuming a cancelled subscription
135+
136+
Users can resume their subscription at any time before the `current_period_end` is reached in their Subscription settings.
137+
138+
When a user resumes their subscription, you will receive the following events:
139+
140+
| Event | Event Trigger |
141+
|-----------------------|-----------------------------------------------------------------------------------------------------------|
142+
| `SUBSCRIPTION_UPDATE` | when the subscription is set to continue with a `status` of `0 (active)` and `canceled_at` is set to null |
143+
144+
---
145+
146+
## Supporting Upgrades and Downgrades
147+
148+
If you offer multiple subscription tiers in your app, users can upgrade or downgrade their subscription at any time from your [Store page](#DOCS_MONETIZATION_MANAGING_SKUS/viewing-your-store-page) or their App Subscription settings.
149+
150+
To create multiple subscription tiers, you will need to [create multiple subscription SKUs](#DOCS_MONETIZATION_MANAGING_SKUS/creating-a-sku) and support the following scenarios in your app:
151+
152+
### Upgrading an existing subscription
153+
154+
If an user is on a lower tier subscription and upgrades to subscription tier that is the same price or higher, the user is charged the difference in price between the two subscriptions and the subscription period resets at the time of upgrading.
155+
156+
When the subscription is upgraded, the current entitlement for the lower tier will end immediately and you will receive the following events:
157+
158+
| Event | Event Trigger |
159+
|-----------------------|--------------------------------------------------------------------------------------------------------------------------|
160+
| `ENTITLEMENT_UPDATE` | when the current entitlement ends. `ends_at` gets updated with a timestamp |
161+
| `ENTITLEMENT_CREATE` | when a new entitlement is created for the upgrade subscription SKU |
162+
| `SUBSCRIPTION_UPDATE` | when the subscription is updated with the new `entitlement_ids`, `sku_ids`, `current_period_start`, `current_period_end` |
163+
164+
165+
### Downgrading an existing subscription
166+
167+
If an user is on a higher tier subscription and downgrades to a lower tier subscription, the user is not charged immediately because the price is lower than what was already paid.
168+
169+
The user has already paid for their current plan until `subscription.current_period_end` so their current plan will be valid until then and you will receive the following event:
170+
171+
| Event | Event Trigger |
172+
|-----------------------|--------------------------------------------------------------------------------------------------|
173+
| `SUBSCRIPTION_UPDATE` | when the subscription is updated to reflect the renewal SKU ID in `subscription.renewal_sku_ids` |
174+
175+
Once the user's current subscription expires on `subscription.current_period_end`, you will receive the following events:
176+
177+
| Event | Event Trigger |
178+
|-----------------------|--------------------------------------------------------------------------------------------------------------------------|
179+
| `ENTITLEMENT_UPDATE` | when the current entitlement ends. `ends_at` gets updated with a timestamp |
180+
| `ENTITLEMENT_CREATE` | when a new entitlement is created for the downgraded subscription SKU |
181+
| `SUBSCRIPTION_UPDATE` | when the subscription is updated with the new `entitlement_ids`, `sku_ids`, `current_period_start`, `current_period_end` |
182+
94183
---
95184

96185
## Using the Subscription API
97186

98187
> info
99188
> When implementing monetization, [Entitlements](#DOCS_RESOURCES_ENTITLEMENT) should be considered the source of truth for a user's access to a specific SKU. The Subscription API is intended for reporting and lifecycle management purposes that happen outside the flow of a user's interaction with your app.
100189
101-
You can use the [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) to check on the status of your app subscriptions. This API allows you to list all subscriptions for your app for reporting purposes and to check on the status of subscriptions without having to access entitlements directly.
190+
You can use the [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) to check on the status of your app subscriptions. This API allows you to list subscriptions by user for reporting purposes and to check on the status of subscriptions without having to access entitlements directly.
102191

103192
- [List SKU Subscriptions](#DOCS_RESOURCES_SUBSCRIPTION/list-sku-subscriptions): List all subscriptions for a specific SKU in your app.
104193
- [Get SKU Subscription](#DOCS_RESOURCES_SUBSCRIPTION/get-sku-subscription): Get a specific subscription in your app.

‎docs/monetization/Managing_SKUs.mdx

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,19 @@ When you click on `Create SKU`, you have the option to select from the following
1919

2020
Once you select the SKU type, enter a name for your SKU to continue.
2121

22+
### Creating Subscription Tiers
23+
24+
You can create multiple subscription tiers to offer different benefits at different price points. Each tier can have its own set of benefits and price and is represented by unique SKUs.
25+
26+
To support upgrading and downgrading between subscription tiers, see our guide on [Implementing App Subscriptions](#DOCS_MONETIZATION_IMPLEMENTING_APP_SUBSCRIPTIONS/supporting-upgrades-and-downgrades).
27+
28+
![Supporting multiple subscription tiers](multisub.png)
29+
2230
### SKU Limitations
2331

2432
There are some limitations to the number of SKUs you can create:
2533
- You can create up to 50 total SKUs per app.
26-
- Currently, you can only have **one** published subscription SKU per app (user or guild).
34+
- You can offer either user subscription SKUs or guild subscription SKUs, but not both simultaneously.
2735
- SKU prices must be selected from the list of available prices.
2836

2937
> info
@@ -162,7 +170,7 @@ Users can access an app's Store page from the Bot User's profile in a server. Th
162170
![Accessing the store as a user](botuser-profile.png)
163171

164172
#### Subscriptions in Your Store page
165-
![Subscriptions in your Store View](premium-subscriptions.png)
173+
![Subscriptions in your Store View](multisub.png)
166174

167175
#### Items in Your Store page
168176
![Items in your Store View](premium-items.png)

‎docs/resources/Subscription.md

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,18 @@ Subscriptions in Discord represent a user making recurring payments for at least
88

99
## Subscription Object
1010

11-
| Field | Type | Description |
12-
|----------------------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
13-
| id | snowflake | ID of the subscription |
14-
| user_id | snowflake | ID of the user who is subscribed |
15-
| sku_ids | array of snowflakes | List of SKUs subscribed to |
16-
| entitlement_ids | array of snowflakes | List of entitlements granted for this subscription |
17-
| current_period_start | ISO8601 timestamp | Start of the current subscription period |
18-
| current_period_end | ISO8601 timestamp | End of the current subscription period |
19-
| status | SubscriptionStatus | Current status of the subscription |
20-
| canceled_at | ISO8601 timestamp? | When the subscription was canceled |
21-
| country? | string | ISO3166-1 alpha-2 country code of the payment source used to purchase the subscription. Missing unless queried with a private OAuth scope. |
11+
| Field | Type | Description |
12+
|----------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
13+
| id | snowflake | ID of the subscription |
14+
| user_id | snowflake | ID of the user who is subscribed |
15+
| sku_ids | array of snowflakes | List of SKUs subscribed to |
16+
| entitlement_ids | array of snowflakes | List of entitlements granted for this subscription |
17+
| renewal_sku_ids | ?array of snowflakes | List of SKUs that this user will be subscribed to at renewal |
18+
| current_period_start | ISO8601 timestamp | Start of the current subscription period |
19+
| current_period_end | ISO8601 timestamp | End of the current subscription period |
20+
| status | SubscriptionStatus | Current status of the subscription |
21+
| canceled_at | ?ISO8601 timestamp | When the subscription was canceled |
22+
| country? | string | ISO3166-1 alpha-2 country code of the payment source used to purchase the subscription. Missing unless queried with a private OAuth scope. |
2223

2324
The start of a subscription is determined by its ID. When the subscription renews, its current period is updated.
2425

@@ -32,6 +33,7 @@ If the user cancels the subscription, the subscription will enter the `ENDING` s
3233
"user_id": "1088605110638227537",
3334
"sku_ids": ["1158857122189168803"],
3435
"entitlement_ids": [],
36+
"renewal_sku_ids": null,
3537
"current_period_start": "2024-08-27T19:48:44.406602+00:00",
3638
"current_period_end": "2024-09-27T19:48:44.406602+00:00",
3739
"status": 0,

‎images/multisub.png

506 KB
Loading

0 commit comments

Comments
 (0)