|
| 1 | +--- |
| 2 | +title: "Premium Apps: Entitlement Migration and New Subscription API" |
| 3 | +date: "2024-08-28" |
| 4 | +topics: |
| 5 | +- "Premium Apps" |
| 6 | +breaking: true |
| 7 | +--- |
| 8 | + |
| 9 | +We are migrating our entitlement system to a new behavior where entitlements will not end until explicitly canceled, representing a breaking change for subscription management. We are introducing a [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) and [Subscription Events](#DOCS_TOPICS_GATEWAY_EVENTS/subscriptions) to allow handling subscription-related events. |
| 10 | + |
| 11 | +> warn |
| 12 | +> This change will be rolled out to all existing applications that have entitlements for user and guild subscription SKUs, starting on October 1, 2024. |
| 13 | +
|
| 14 | +#### Entitlement Migration Details |
| 15 | +- `ENTITLEMENT_CREATE` events will now be triggered with a null `ends_at` value for all ongoing subscriptions, indicating an indefinite entitlement. |
| 16 | +- `ENTITLEMENT_UPDATE` events will occur only when a subscription is canceled, with the `ends_at` value indicating the end date. |
| 17 | +- Discord-managed Subscription entitlements will have an `type` value of `PURCHASE` (type `1`) instead of `APPLICATION_SUBSCRIPTION` (type `8`). |
| 18 | + |
| 19 | +### Migration Plan & Guide: |
| 20 | +As of **October 1, 2024**, all existing entitlements that grant access to user-subscription and guild-subscription SKUs will automatically transfer to the new system on their renewal date. This means we will have a month-long migration window to allow all of your entitlements to migrate to the new system upon renewal. |
| 21 | + |
| 22 | +Developers are advised to update their systems to handle the new `ENTITLEMENT_CREATE` and `ENTITLEMENT_UPDATE` events according to the following migration guide before the rollout date to avoid service disruptions. |
| 23 | + |
| 24 | +### Introducing a New Subscription API |
| 25 | +With the new entitlement behavior, entitlements for subscription SKUs will no longer emit events at the start of a new subscription billing period. Instead, subscription lifecycle management can be handled through the new [Subscription API](#DOCS_MONETIZATION_IMPLEMENTING_APP_SUBSCRIPTIONS/using-the-subscription-api). |
| 26 | +Developers should refer to the [Subscription resource](#DOCS_RESOURCES_SUBSCRIPTION) for information on calling the Subscription API and responding to Subscription events. For in-depth implementation details, see our [Implementing App Subscriptions](#DOCS_MONETIZATION_IMPLEMENTING_APP_SUBSCRIPTIONS/using-the-subscription-api) guide. You can start using this API now. |
| 27 | + |
| 28 | +### Monetization Documentation Updates |
| 29 | +As part of these changes, we've updated the documentation for Premium Apps. |
| 30 | +- Created a new [Enabling Monetization](#DOCS_MONETIZATION_ENABLING_MONETIZATION) page to cover setting up your team, managing payouts, and enabling monetization for your apps |
| 31 | +- Created a new [Managing SKUs](#DOCS_MONETIZATION_MANAGING_SKUS/creating-a-sku) page to document how to create, update, publish, and promote your SKUs |
| 32 | +- Moved and added [Entitlement](#DOCS_RESOURCES_ENTITLEMENT), [SKU](#DOCS_RESOURCES_SKU) and [Subscription](#DOCS_RESOURCES_SUBSCRIPTION) resources to the **Resources** section |
| 33 | +- Updated guides for [Implementing App Subscriptions](#DOCS_MONETIZATION_IMPLEMENTING_APP_SUBSCRIPTIONS) and [Implementing One-Time Purchases](#DOCS_MONETIZATION_IMPLEMENTING_ONE-TIME_PURCHASES) |
| 34 | + |
| 35 | +### Subscription Entitlement Migration Guide |
| 36 | + |
| 37 | +Starting on **October 1, 2024**, we will be migrating our existing entitlement system to a new behavior where **entitlements do not expire until explicitly canceled**. This migration guide outlines the changes and impacts of this migration on developers and guides how to manage these changes effectively. |
| 38 | + |
| 39 | +> warn |
| 40 | +> With this update, entitlements for subscription SKUs will no longer emit events when a new subscription billing period begins. If you need to know when a subscription has been renewed, use the new [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) and related [Subscription Gateway Events](#DOCS_TOPICS_GATEWAY_EVENTS/subscriptions). |
| 41 | +
|
| 42 | +### Current System |
| 43 | + |
| 44 | +Currently, entitlements for Subscription SKUs purchased through Discord have: |
| 45 | +- An `ends_at` date that corresponds to the subscription interval. This date is updated at each billing cycle. |
| 46 | +- A entitlement `type` value of `APPLICATION_SUBSCRIPTION` (type `8`). |
| 47 | +- An `ENTITLEMENT_UPDATE` event is triggered at the start of each new subscription period. |
| 48 | + |
| 49 | +### New System |
| 50 | + |
| 51 | +Post-migration, entitlements for Subscription SKUs purchased through Discord will: |
| 52 | +- No longer have an end date (`ends_at` will be `null`) until the user decides to cancel the subscription. |
| 53 | +- Now have an entitlement `type` value of `PURCHASE` (type `1`). |
| 54 | +- No `ENTITLEMENT_UPDATE` events will be triggered until the subscription is canceled. |
| 55 | + |
| 56 | +### Migration Timeline |
| 57 | + |
| 58 | +- **Migration Start Date:** October 1, 2024 |
| 59 | +- **Migration End Date:** October 31, 2024 |
| 60 | + |
| 61 | +### Migration Impacts |
| 62 | + |
| 63 | +### 1) Existing Entitlements Scheduled to Renew |
| 64 | + |
| 65 | +- **During Migration Window:** |
| 66 | + - These will automatically transfer to the new system. |
| 67 | + - A new `ENTITLEMENT_CREATE` event will be triggered to indicate the migration. This does not indicate a net new entitlement. |
| 68 | + - No further events will be generated until cancellation, which will then trigger an `ENTITLEMENT_UPDATE` event. |
| 69 | + |
| 70 | +### 2) Existing Entitlements Set to End |
| 71 | + |
| 72 | +- **During Migration Window:** |
| 73 | + - These entitlements will naturally expire and not renew under the new system. |
| 74 | + - No new entitlement events will be generated for these cases. |
| 75 | + |
| 76 | +### Developer Actions |
| 77 | +- **Pre-Migration:** |
| 78 | + - Review and understand the new entitlement event structure. |
| 79 | + - Adjust your system to handle `ends_at` being null, which now indicates an indefinite entitlement. |
| 80 | + - Adjust your system not to expect type `APPLICATION_SUBSCRIPTION` (type `8`) for Discord-managed subscription entitlements. |
| 81 | +- **Post-Migration:** |
| 82 | + - Monitor for `ENTITLEMENT_CREATE` and `ENTITLEMENT_UPDATE` events. |
| 83 | + - Update your handling of `ends_at` timestamps to manage cancellations effectively. |
| 84 | + |
| 85 | +<Collapsible title="Entitlement Migration Example Scenario" description="Step-by-step example of an entitlement upgrading to the new entitlement system" icon="view" open> |
| 86 | +- The Entitlement Migration begins on October 1, 2024 |
| 87 | +- You have an existing user subscription that has an existing `ends_at` timestamp for October 10, 2024. |
| 88 | +- If the subscription renews successfully, you will receive an `ENTITLEMENT_UPDATE` event on October 10, 2024, with an `ends_at` value of null |
| 89 | +- If you receive an `ENTITLEMENT_UPDATE` event with an `ends_at` timestamp, the entitlement for this subscription is expected to end at the timestamp value unless you receive subsequent `ENTITLEMENT_UPDATE` events between the cancellation and the `ends_at` value. |
| 90 | +</Collapsible> |
0 commit comments