You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/Change_Log.md
+28Lines changed: 28 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,33 @@
1
1
# Change Log
2
2
3
+
## Premium Apps: One-Time Purchases and Store
4
+
5
+
#### April 24, 2024
6
+
7
+
Two new features are now available for Premium Apps: One-Time Purchases and Stores.
8
+
9
+
**One-Time Purchases**
10
+
11
+
-**Durable Items**: A one-time purchase that is permanent and is not subject to either renewal or consumption, such as lifetime access to an app's premium features.
12
+
-**Consumable Items**: A one-time, non-renewable purchase that provides access, such as a temporary power-up or boost in a game.
13
+
14
+
Learn more about implementing [One-Time Purchases](#DOCS_MONETIZATION_ONE-TIME_PURCHASES).
15
+
16
+
**A Store for Your Premium App**
17
+
18
+
We have also introduced a Store for your Premium App to showcase your app subscriptions and one-time purchase items. You can now create a unique Store page within the developer portal and add your published subscription SKUs or one-time purchase SKUs to your store view, allowing your users to buy these items from your App Directory or Bot User Profile.
19
+
20
+
To explore these features, eligibility details, and how to enable monetization for your app, check out the [Monetization Overview](#DOCS_MONETIZATION_OVERVIEW).
21
+
22
+
**API Documentation Updates**
23
+
24
+
The following were added to our public Monetization documentation with this update:
25
+
26
+
- New [SKU Object Types](#DOCS_MONETIZATION_SKUS/sku-object-sku-types)
27
+
- New [Entitlement Object Types](#DOCS_MONETIZATION_ENTITLEMENTS/entitlement-object-entitlement-types)
28
+
-[Consume an Entitlement](#DOCS_MONETIZATION_ENTITLEMENTS/consume-an-entitlement) API endpoint
29
+
-`consumed` field on the [Entitlement](#DOCS_MONETIZATION_ENTITLEMENTS) resource
| DEVELOPER_GIFT | 3 | Entitlement was gifted by developer |
49
+
| TEST_MODE_PURCHASE | 4 | Entitlement was purchased by a dev in application test mode |
50
+
| FREE_PURCHASE | 5 | Entitlement was granted when the SKU was free |
51
+
| USER_GIFT | 6 | Entitlement was gifted by another user |
52
+
| PREMIUM_PURCHASE | 7 | Entitlement was claimed by user for free as a Nitro Subscriber |
53
+
| APPLICATION_SUBSCRIPTION | 8 | Entitlement was purchased as an app subscription |
46
54
47
55
## List Entitlements % GET /applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/entitlements
48
56
@@ -62,24 +70,30 @@ Returns all entitlements for a given app, active and expired.
62
70
63
71
```json
64
72
[
65
-
{
66
-
"id": "1019653849998299136",
67
-
"sku_id": "1019475255913222144",
68
-
"application_id": "1019370614521200640",
69
-
"user_id": "771129655544643584",
70
-
"promotion_id": null,
71
-
"type": 8,
72
-
"deleted": false,
73
-
"gift_code_flags": 0,
74
-
"consumed": false,
75
-
"starts_at": "2022-09-14T17:00:18.704163+00:00",
76
-
"ends_at": "2022-10-14T17:00:18.704163+00:00",
77
-
"guild_id": "1015034326372454400",
78
-
"subscription_id": "1019653835926409216"
79
-
}
73
+
{
74
+
"id": "1019653849998299136",
75
+
"sku_id": "1019475255913222144",
76
+
"application_id": "1019370614521200640",
77
+
"user_id": "771129655544643584",
78
+
"promotion_id": null,
79
+
"type": 8,
80
+
"deleted": false,
81
+
"gift_code_flags": 0,
82
+
"consumed": false,
83
+
"starts_at": "2022-09-14T17:00:18.704163+00:00",
84
+
"ends_at": "2022-10-14T17:00:18.704163+00:00",
85
+
"guild_id": "1015034326372454400",
86
+
"subscription_id": "1019653835926409216"
87
+
}
80
88
]
81
89
```
82
90
91
+
## Consume an Entitlement % POST /applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/entitlements/{entitlement.id#DOCS_MONETIZATION_ENTITLEMENTS/entitlement-object}/consume
92
+
93
+
For One-Time Purchase consumable SKUs, marks a given entitlement for the user as consumed. The entitlement will have `consumed: true` when using [List Entitlements](#DOCS_MONETIZATION_ENTITLEMENTS/list-entitlements).
94
+
95
+
Returns a `204 No Content` on success.
96
+
83
97
## Create Test Entitlement % POST /applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/entitlements
84
98
85
99
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.
@@ -98,9 +112,9 @@ After creating a test entitlement, you'll need to reload your Discord client. Af
98
112
99
113
```json
100
114
{
101
-
"sku_id": "999184799365857331",
102
-
"owner_id": "847184799365857999",
103
-
"owner_type": 1
115
+
"sku_id": "999184799365857331",
116
+
"owner_id": "847184799365857999",
117
+
"owner_type": 1
104
118
}
105
119
```
106
120
@@ -122,18 +136,18 @@ Fires when a user subscribes to a SKU. Contains an entitlement object.
122
136
123
137
```json
124
138
{
125
-
"id": "1083167266843000832",
126
-
"sku_id": "1083142056391606272",
127
-
"application_id": "1083108937882013696",
128
-
"user_id": "1072239583707664384",
129
-
"promotion_id": null,
130
-
"type": 8,
131
-
"deleted": false,
132
-
"gift_code_flags": 0,
133
-
"consumed": false,
134
-
"starts_at": "2023-03-08T23:19:58.010876+00:00",
135
-
"ends_at": "2023-04-08T23:19:58.010876+00:00",
136
-
"subscription_id": "1083167255652597760"
139
+
"id": "1083167266843000832",
140
+
"sku_id": "1083142056391606272",
141
+
"application_id": "1083108937882013696",
142
+
"user_id": "1072239583707664384",
143
+
"promotion_id": null,
144
+
"type": 8,
145
+
"deleted": false,
146
+
"gift_code_flags": 0,
147
+
"consumed": false,
148
+
"starts_at": "2023-03-08T23:19:58.010876+00:00",
149
+
"ends_at": "2023-04-08T23:19:58.010876+00:00",
150
+
"subscription_id": "1083167255652597760"
137
151
}
138
152
```
139
153
@@ -151,8 +165,8 @@ If a user's subscription is cancelled, you will _not_ receive an `ENTITLEMENT_DE
151
165
152
166
Fires when a user's entitlement is deleted. Entitlement deletions are infrequent, and occur when:
153
167
154
-
-Discord issues a refund for a subscription
155
-
-Discord removes an entitlement from a user via internal tooling
168
+
- Discord issues a refund for a subscription
169
+
- Discord removes an entitlement from a user via internal tooling
156
170
157
171
Entitlements are _not_ deleted when they expire.
158
172
@@ -170,8 +184,8 @@ This response will create an ephemeral message shown to the user that ran the in
170
184
171
185
```js
172
186
returnres.send({
173
-
type:InteractionResponseType.PREMIUM_REQUIRED, // This has a value of 10
174
-
data: {},
187
+
type:InteractionResponseType.PREMIUM_REQUIRED, // This has a value of 10
Developers now have the ability to set up a Store page in the Developer Portal. To set up your Premium App's Store view take the following steps:
4
+
5
+
- Create a SKU
6
+
- Add a SKU image and benefits
7
+
- Implement the SKU into your app
8
+
- Publish a SKU to your store view with the click of a button.
9
+
10
+
## Adding SKUs to your Store
11
+
12
+
Once you've created SKUs for an [App Subscription](#DOCS_MONETIZATION_APP_SUBSCRIPTIONS) or [One-Time Purchase](#DOCS_MONETIZATION_ONE-TIME_PURCHASES), you can add those SKUs to your Store to make them available for purchase by your users.
13
+
14
+
### Manage SKUs
15
+
While creating and editing SKUs in your [app's settings](https://discord.com/developers/applications) on the `Monetization -> Manage SKUs` tab, you have a few options for managing your SKUs visibility and publishing to your users:
16
+
17
+
-**Add to store**: Will add a published SKU to your Store
18
+
-**Remove from store**: Will remove a published SKU from your Store, keeping it published to the API
19
+
-**Publish SKU**: Will let you publish a new SKU and make it **Available via Store & API** or **Available via API Only**.
20
+
-**Unpublish SKU**: Will unpublish the SKU from both the Store and the API. Users who already have this SKU will still be entitled to the SKU even if it becomes unpublished. You can republish a SKU at any time.
21
+
22
+
> preview
23
+
> We will have more updates on publishing SKUs to the API vs the Store as we release more monetization features.
24
+
25
+
### Manage Store
26
+
Under the `Monetization -> Manage Store` tab, you can organize your SKUs for both subscriptions and items. You can add new or existing SKUs or update the order your SKUs appear to your users in the Store.
27
+
28
+
> info
29
+
> Currently you can only have one Subscription published on your app and in your Store.
30
+
31
+
## User Access for Your Store
32
+
33
+
Users can now access an App's store page from the Bot User's profile in a server. This allows users to view an available subscription and one-time purchases, select a subscription to view its perks, benefits and details, and make a purchase directly from an App's Store page.
34
+
35
+
36
+
37
+
### Viewing Subscriptions in Your Store
38
+
39
+
Currently, you can only have one active App Subscription SKU for your app. If your app has either a user or guild subscription, you can add it to your Store for users to purchase.
40
+
41
+
> preview
42
+
> Support for multiple subscription SKUs is coming soon.
43
+
44
+
45
+
46
+
### Viewing Items in Your Store
47
+
48
+
As you build out your One-Time Purchase SKUs, you can add as many durable and consumable items to your Store as needed by your app.
One-time purchases enable you to charge your users for premium functionality with in-app items. Before you can add one-time purchases to your app, you must complete the [Monetization Eligibility Checklist](#DOCS_MONETIZATION_OVERVIEW/eligibility-checklist) in your [app's settings](https://discord.com/developers/applications).
4
+
5
+
Once you've confirmed eligibility for your app and team, you will be able to set up a [SKU](#DOCS_MONETIZATION_SKUS) (stock-keeping unit) to represent your app's premium offering via subscriptions or items.
6
+
7
+
## Types of One-Time Purchases
8
+
9
+
When creating items for one-time purchase, you can choose between durable and consumable items:
10
+
11
+
-**Durable Items**: A one-time purchase that is permanent and is not subject to either renewal or consumption, such as lifetime access to an app's premium features.
12
+
-**Consumable Items**: A one-time, non-renewable purchase that provides access, such as a temporary power-up or boost in a game.
13
+
14
+
You can offer as many one-time purchase SKUs as needed by your app.
15
+
16
+
## Configuring One-Time Purchases
17
+
18
+
Once you have an idea what type of items you want to offer for your app, you can create either durable or consumable SKUs to reflect the benefits that the user will receive from purchasing your new item.
19
+
20
+
As you are setting up a new SKU, you can configure:
21
+
22
+
- SKU Image
23
+
- Name
24
+
- Product Description
25
+
- Price
26
+
27
+
28
+
29
+
## Publishing Your One-Time Purchases
30
+
31
+
Once you have configured your SKU, you can publish the SKU to either just the API or the API and your Store. Learn more about [Managing Your Store](#DOCS_MONETIZATION_MANAGING_YOUR_STORE) to curate what items you make available to your users.
32
+
33
+
34
+
35
+
## Implementing One-Time Purchases
36
+
37
+
When a user subscribes to your app, there are a few things you will need to implement in your code to check for subscription status and access.
38
+
39
+
- Working with Entitlements
40
+
- Handling Gateway Events for Entitlements
41
+
- Handling Entitlements for Consumable SKUs
42
+
43
+
### Keeping Track of Entitlements
44
+
45
+
When a user purchases a one-time purchase SKU, an entitlement is created. [Entitlements](#DOCS_MONETIZATION_ENTITLEMENTS) represent the user's access to your consumable or durable item. You can keep track of entitlements using Gateway Events and the HTTP API.
46
+
47
+
#### Entitlement Gateway Events
48
+
49
+
When users subscribe or renew a subscription with your app, Discord will emit [entitlement gateway events](#DOCS_MONETIZATION_ENTITLEMENTS/gateway-events).
50
+
51
+
Upon a user's purchase of a SKU, you'll receive an [`ENTITLEMENT_CREATE`](#DOCS_MONETIZATION_ENTITLEMENTS/new-entitlement) event.
52
+
53
+
#### Entitlement HTTP Endpoints
54
+
55
+
For apps requiring background processing, keeping track of entitlements is essential. You can utilize the [List Entitlements](#DOCS_MONETIZATION_ENTITLEMENTS/list-entitlements) endpoint to list entitlements. Your app can filter entitlements by a specific user or set of SKUs by using the `?user_id=XYZ` or `?sku_ids=XYZ` query params.
56
+
57
+
#### Handling Consumable One-Time Purchases
58
+
59
+
When offering consumable items, users can only have one unconsumed entitlement at a time. In order to handle consumable items in your app or game, you should process and store the consumable item in your app and then make a call to the [Consume Entitlement](#DOCS_MONETIZATION_ENTITLEMENTS/consume-an-entitlement) endpoint so that the user can purchase more of this item in the future.
60
+
61
+
Consuming the entitlement will update the entitlement to return a true value in the entitlement's `consumed` field. You will need to think through how your app uses consumable items to decide on the best strategy for when to consume these entitlements.
62
+
63
+
## Testing Your Implementation
64
+
65
+
> warn
66
+
> The method of testing purchases for One-Time Purchases differs from the method for App Subscriptions. **Do NOT use Test Entitlements for One-Time Purchases.**
67
+
68
+
### Using Application Test Mode
69
+
70
+
While in Application Test Mode, you can freely make "purchases" of One-Time Purchase SKUs tied to your application. That means you can test buying your consumable and durable items by going through the IAP flow without any credit card charges.
71
+
72
+
> info
73
+
> You still need to have a valid payment method on file to "purchase" SKUs in Application Test Mode. It just won't be charged at checkout.
74
+
75
+
To enable it, first make sure you have a payment method on file in User Settings -> Billing and then:
76
+
77
+
1. Open up the Discord app
78
+
2. Click on the Settings cog in the bottom left corner
79
+
3. Go to the `Advanced` page under App Settings
80
+
4. Toggle "Developer Mode" **on** and "Application Test Mode" **on**, and enter your application ID. You can leave the other settings as-is.
81
+
5. Exit user settings
82
+
83
+
Once you enabled Application Test Mode successfully, you should now see an orange bar across the top of your screen with the name of your app.
84
+
85
+
You can now navigate to your [Store](#DOCS_MONETIZATION_MANAGING_YOUR_STORE) page and purchase your one-time purchase items without being charged.
86
+
87
+
The entitlements tied to items that are purchased in Application Test Mode can be identified by entitlements with a `type` value of 4 to represent `TEST_MODE_PURCHASE`.
88
+
89
+
> info
90
+
> The "Go To SKU" button does not currently work. There will be an update there soon. To purchase your SKU in test mode, go to your Store page.
91
+
92
+
## Receiving Payouts
93
+
94
+
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.
95
+
96
+
For more information, read the [Premium Apps Payouts](https://support-dev.discord.com/hc/articles/17299902720919) Help Center article.
| SUBSCRIPTION | 5 | Represents a recurring subscription |
45
47
| SUBSCRIPTION_GROUP | 6 | System-generated group for each SUBSCRIPTION SKU created |
46
48
@@ -110,7 +112,10 @@ Congratulations on going live! 🥳
110
112
111
113
## List SKUs % GET /applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/skus
112
114
113
-
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`.
115
+
Returns all SKUs for a given application.
116
+
117
+
> info
118
+
> Because of how our SKU and subscription systems work, you will see two SKUs for your subscription offering. For integration and testing entitlements for Subscriptions, you should use the SKU with `type: 5`.
0 commit comments