Entitlement

Reference for Discord entitlement objects that represent user or guild access to premium offerings in your application.

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

id · snowflake · required

ID of the entitlement.

sku_id · snowflake · required

ID of the SKU.

application_id · snowflake · required

ID of the parent application.

user_id · snowflake

ID of the user that is granted access to the entitlement’s SKU. Optional field.

type · integer · required

Type of entitlement.

deleted · boolean · required

Whether the entitlement was deleted.

starts_at · ?ISO8601 timestamp · required

Start date at which the entitlement is valid. null for test entitlements.

ends_at · ?ISO8601 timestamp · required

Date at which the entitlement is no longer valid. null for test entitlements.

guild_id · snowflake

ID of the guild that is granted access to the entitlement’s SKU. Optional field.

consumed · boolean

For consumable items, whether the entitlement has been consumed. Optional field.

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

Type	Value	Description
PURCHASE	1	Entitlement was purchased by user
PREMIUM_SUBSCRIPTION	2	Entitlement for Discord Nitro subscription
DEVELOPER_GIFT	3	Entitlement was gifted by developer
TEST_MODE_PURCHASE	4	Entitlement was purchased by a dev in application test mode
FREE_PURCHASE	5	Entitlement was granted when the SKU was free
USER_GIFT	6	Entitlement was gifted by another user
PREMIUM_PURCHASE	7	Entitlement was claimed by user for free as a Nitro Subscriber
APPLICATION_SUBSCRIPTION	8	Entitlement was purchased as an app subscription

---

List entitlements

GET /applications/{application.id}/entitlements

Returns all entitlements for a given app, both active and expired.

Query string params

user_id · snowflake

User ID to look up entitlements for.

sku_ids · comma-delimited set of snowflakes

Optional list of SKU IDs to check entitlements for.

before · snowflake

Retrieve entitlements before this entitlement ID.

after · snowflake

Retrieve entitlements after this entitlement ID.

limit · integer · default: "100"

Number of entitlements to return (1–100).

guild_id · snowflake

Guild ID to look up entitlements for.

exclude_ended · boolean · default: "false"

Whether to omit ended entitlements. Defaults to false — ended entitlements are included by default.

exclude_deleted · boolean · default: "true"

Whether to omit deleted entitlements. Defaults to true — deleted entitlements are not included by default.

Response 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"
  }
]

Get entitlement

GET /applications/{application.id}/entitlements/{entitlement.id}

Returns a single entitlement object.

{
  "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 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, reload your Discord client. Your server or user will then have premium access.

JSON params

sku_id · string · required

ID of the SKU to grant the entitlement to.

owner_id · string · required

ID of the guild or user to grant the entitlement to.

owner_type · integer · required

1 for a guild subscription, 2 for a user subscription.

Request example

{
  "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.