Skip to main content
Entitlements in Discord represent that a user or guild has access to a premium offering in your application. Refer to the Monetization Overview for more information on how to use Entitlements in your app.

​
Entitlement Object

Entitlement Structure
FieldTypeDescription
idsnowflakeID of the entitlement
sku_idsnowflakeID of the SKU
application_idsnowflakeID of the parent application
user_id?snowflakeID of the user that is granted access to the entitlement’s sku
typeintegerType of entitlement
deletedbooleanEntitlement was deleted
starts_at?ISO8601 timestampStart date at which the entitlement is valid.
ends_at?ISO8601 timestampDate at which the entitlement is no longer valid.
guild_id?snowflakeID of the guild that is granted access to the entitlement’s sku
consumed?booleanFor consumable items, whether or not the entitlement has been consumed
Entitlement Example
{
  "id": "1019653849998299136",
  "sku_id": "1019475255913222144",
  "application_id": "1019370614521200640",
  "user_id": "771129655544643584",
  "promotion_id": null,
  "type": 8,
  "deleted": false,
  "gift_code_flags": 0,
  "consumed": false,
  "starts_at": "2022-09-14T17:00:18.704163+00:00",
  "ends_at": "2022-10-14T17:00:18.704163+00:00",
  "guild_id": "1015034326372454400",
  "subscription_id": "1019653835926409216"
}
Entitlement Types
TypeValueDescription
PURCHASE1Entitlement was purchased by user
PREMIUM_SUBSCRIPTION2Entitlement for Discord Nitro subscription
DEVELOPER_GIFT3Entitlement was gifted by developer
TEST_MODE_PURCHASE4Entitlement was purchased by a dev in application test mode
FREE_PURCHASE5Entitlement was granted when the SKU was free
USER_GIFT6Entitlement was gifted by another user
PREMIUM_PURCHASE7Entitlement was claimed by user for free as a Nitro Subscriber
APPLICATION_SUBSCRIPTION8Entitlement was purchased as an app subscription

​
List Entitlements

GET/applications/{application.id}/entitlements
Returns all entitlements for a given app, active and expired.
Query String Params
paramtypedescription
user_id?snowflakeUser ID to look up entitlements for
sku_ids?comma-delimited set of snowflakesOptional list of SKU IDs to check entitlements for
before?snowflakeRetrieve entitlements before this entitlement ID
after?snowflakeRetrieve entitlements after this entitlement ID
limit?integerNumber of entitlements to return, 1-100, default 100
guild_id?snowflakeGuild ID to look up entitlements for
exclude_ended?booleanWhether or not ended entitlements should be omitted. Defaults to false, ended entitlements are included by default.
exclude_deleted?booleanWhether or not deleted entitlements should be omitted. Defaults to true, deleted entitlements are not included by default.
[
  {
    "id": "1019653849998299136",
    "sku_id": "1019475255913222144",
    "application_id": "1019370614521200640",
    "user_id": "771129655544643584",
    "promotion_id": null,
    "type": 8,
    "deleted": false,
    "gift_code_flags": 0,
    "consumed": false,
    "starts_at": "2022-09-14T17:00:18.704163+00:00",
    "ends_at": "2022-10-14T17:00:18.704163+00:00",
    "guild_id": "1015034326372454400",
    "subscription_id": "1019653835926409216"
  }
]

​
Get Entitlement

GET/applications/{application.id}/entitlements/{entitlement.id}
Returns an entitlement. 
{
  "id": "1019653849998299136",
  "sku_id": "1019475255913222144",
  "application_id": "1019370614521200640",
  "user_id": "771129655544643584",
  "promotion_id": null,
  "type": 8,
  "deleted": false,
  "gift_code_flags": 0,
  "consumed": false,
  "starts_at": "2022-09-14T17:00:18.704163+00:00",
  "ends_at": "2022-10-14T17:00:18.704163+00:00",
  "guild_id": "1015034326372454400",
  "subscription_id": "1019653835926409216"
}

​
Consume an Entitlement

POST/applications/{application.id}/entitlements/{entitlement.id}/consume
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. Returns a 204 No Content on success.

​
Create Test Entitlement

POST/applications/{application.id}/entitlements
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. This endpoint returns a partial entitlement object. It will not contain subscription_id, starts_at, or ends_at, as it’s valid in perpetuity. After creating a test entitlement, you’ll need to reload your Discord client. After doing so, you’ll see that your server or user now has premium access.
JSON Params
paramtypedescription
sku_idstringID of the SKU to grant the entitlement to
owner_idstringID of the guild or user to grant the entitlement to
owner_typeinteger1 for a guild subscription, 2 for a user subscription
{
  "sku_id": "999184799365857331",
  "owner_id": "847184799365857999",
  "owner_type": 1
}

​
Delete Test Entitlement

DELETE/applications/{application.id}/entitlements/{entitlement.id}
Deletes a currently-active test entitlement. Discord will act as though that user or guild no longer has entitlement to your premium offering. Returns 204 No Content on success.