|
| 1 | +--- |
| 2 | +description: Add premium features to your bot. |
| 3 | +--- |
| 4 | + |
| 5 | +# Monetization |
| 6 | + |
| 7 | +:::note |
| 8 | + |
| 9 | +Monetization is limited to **verified** apps/bots. |
| 10 | + |
| 11 | +::: |
| 12 | + |
| 13 | +Premium Apps offer developers the ability to monetize their application through either **monthly recurring subscriptions** or **one-time purchases**, natively on Discord. |
| 14 | +This allows you to e.g. limit specific commands or other functionality to premium users/guilds. |
| 15 | + |
| 16 | +Not all applications are eligible - your app must be verified, part of a developer team, and use [slash commands](/interactions/slash-commands) or the privileged `Message Content` intent, among other things. |
| 17 | + |
| 18 | +## Initial setup |
| 19 | + |
| 20 | +To get started, visit the [official documentation](https://discord.com/developers/docs/monetization/overview) to see the full list of requirements, and configure your app for monetization by following the steps outlined there. |
| 21 | + |
| 22 | +## Entitlements |
| 23 | + |
| 24 | +Entitlements represent access to the premium functionality of your application. These can be granted to users or guilds, depending on the type of SKU you set up in the previous step. |
| 25 | + |
| 26 | +In [interactions](/interactions) (e.g. slash commands), the entitlements for the invoking user/guild are easily accessible using <DocsLink reference="disnake.Interaction.entitlements" />. |
| 27 | + |
| 28 | +Outside of interactions, you can fetch entitlements using <DocsLink reference="disnake.Client.entitlements">Client.entitlements()</DocsLink>, optionally only fetching entitlements of a specific user or guild. Note that this may include expired entitlements, unless you pass the `exclude_ended` parameter. |
| 29 | + |
| 30 | +To check whether an entitlement is still active, you can use <DocsLink reference="disnake.Entitlement.is_active">Entitlement.is_active()</DocsLink>. |
| 31 | + |
| 32 | +### Premium interactions |
| 33 | + |
| 34 | +This is usually the main way to provide premium functionality. |
| 35 | +Commands are not preemptively marked as "premium-only" - instead, you may respond with a premium button, prompting users to upgrade/purchase a specific SKU: |
| 36 | + |
| 37 | +```python |
| 38 | +sku_id = 1234432112344321 |
| 39 | + |
| 40 | + |
| 41 | +@bot.slash_command() |
| 42 | +async def command(inter: disnake.ApplicationCommandInteraction): |
| 43 | + if not any(e.sku_id == sku_id for e in inter.entitlements): |
| 44 | + await inter.response.send( |
| 45 | + content="Upgrade now to get access to this feature!", |
| 46 | + components=[disnake.ui.Button(sku_id=sku_id)], |
| 47 | + ) |
| 48 | + return # skip remaining code |
| 49 | + ... |
| 50 | +``` |
| 51 | + |
| 52 | +<p align="center"> |
| 53 | + <img |
| 54 | + src={require('./images/monetization-response.png').default} |
| 55 | + alt="Premium Interaction Response Type" |
| 56 | + width="75%" |
| 57 | + /> |
| 58 | +</p> |
| 59 | + |
| 60 | +### Events |
| 61 | + |
| 62 | +Whenever users make a purchase in your app, you will receive an <DocsLink reference="disnake.on_entitlement_create" /> event. For subscriptions, entitlements are granted indefinitely until the user decides to cancel their subscription, in which case you will receive a <DocsLink reference="disnake.on_entitlement_update" /> event when the subscription ends. |
| 63 | +Note that entitlement events are not emitted immediately when a subscription is canceled, only at the end of the subscription period. In this case, the entitlement's <DocsLink reference="disnake.Entitlement.ends_at">ends_at</DocsLink> attribute reflects the date indicating when the subscription (and entitlement) ended. |
| 64 | + |
| 65 | +:::note |
| 66 | +While an <DocsLink reference="disnake.on_entitlement_delete" /> event also exists, it will not fire when a subscription expires; it only occurs e.g. in case of refunds or due to manual removal by Discord. |
| 67 | +::: |
| 68 | + |
| 69 | +## Subscriptions |
| 70 | + |
| 71 | +Subscriptions are used for products with recurring monthly payments. These should not be used to determine access to premium features, they are only meant for lifecycle management purposes. |
| 72 | + |
| 73 | +Similarly to entitlements, you will receive an <DocsLink reference="disnake.on_subscription_create" /> event whenever a subscription is created. An <DocsLink reference="disnake.on_subscription_update" /> event is emitted when a user cancels their subscription; canceled subscriptions remain valid until the end of the subscription period. Further details about subscription lifecycles can be found in the [official documentation](https://discord.com/developers/docs/monetization/implementing-app-subscriptions#supporting-subscriptions). |
| 74 | + |
| 75 | +To obtain the subscriptions of a user to a particular SKU, you can use <DocsLink reference="disnake.SKU.subscriptions" />. |
| 76 | + |
| 77 | +### Testing subscriptions |
| 78 | + |
| 79 | +For subscription SKUs, you can create test entitlements using <DocsLink reference="disnake.Client.create_entitlement" /> and delete them using <DocsLink reference="disnake.Entitlement.delete" />, which allows you to test your implementation in various subscription states. These entitlements do not expire and therefore have no start/end date. |
| 80 | + |
| 81 | +If you want to test the full payment flow, you can go through the same upgrade steps as any other user of your application would - all members of the app's associated team automatically receive a 100% discount on the subscription. Note that you cannot delete these entitlements, unlike the test entitlements mentioned before. |
| 82 | + |
| 83 | +## One-time purchases |
| 84 | + |
| 85 | +One-time purchases can be durable (i.e. permanent) or consumable. |
| 86 | +Just like subscriptions, access to these items is represented by entitlements, which you can receive in entitlement events or interactions. |
| 87 | + |
| 88 | +Users may only have one unconsumed entitlement for an SKU at a time. To consume an entitlement, use <DocsLink reference="disnake.Entitlement.consume" /> and process/store the state of the item in your application where applicable. |
| 89 | + |
| 90 | +For further lifecycle details and other considerations, visit the [official documentation](https://discord.com/developers/docs/monetization/implementing-one-time-purchases#how-onetime-purchases-work) for one-time purchases. |
| 91 | + |
| 92 | +### Testing one-time purchases |
| 93 | + |
| 94 | +Unlike subscriptions, one-time purchases may only be tested through the Application Test Mode, not via test entitlements. |
| 95 | +To test one-time purchases without being charged, [enable Application Test Mode](https://discord.com/developers/docs/monetization/implementing-one-time-purchases#using-application-test-mode) for your app and visit the app's store page. |
| 96 | +Entitlements tied to one-time purchases made this way will have a `type` of <DocsLink reference="disnake.EntitlementType.test_mode_purchase">test_mode_purchase</DocsLink>. |
0 commit comments