Subscriptions

Subscriptions in Discord represent an user making recurring payments for at least one SKU over an ongoing period. Successful payments grant the user access to entitlements associated with the SKU.

Subscription Object

Subscription Structure

Field	Type	Description
id	snowflake	The ID of the subscription
type	integer	The type of subscription
payment_gateway	?integer	The payment gateway used to bill the subscription
currency	string	The lower-cased ISO 4217 currency code
items	array[subscription item object]	The items in the subscription
payment_gateway_plan_id	?string	The payment gateway's plan ID for the subscription
payment_gateway_subscription_id?	?string	The payment gateway's subscription ID for the subscription
current_period_start	ISO8601 timestamp	When the current billing period started
current_period_end	ISO8601 timestamp	When the current billing period ends
streak_started_at?	ISO8601 timestamp	When the current subscription streak started
status	integer	The status of subscription
renewal_mutations?	subscription renewal mutations object	The mutations to the subscription that will occur after renewal
trial_id?	snowflake	The ID of the trial the subscription is from
payment_source_id	?snowflake	The ID of the payment source the subscription is paid with
created_at	ISO8601 timestamp	When the subscription was created
canceled_at?	ISO8601 timestamp	When the subscription was canceled
country_code	?string	The ISO 3166-1 alpha-2 country code the subscription is billed in
trial_ends_at?	ISO8601 timestamp	When the trial ends
metadata?	subscription metadata object	Extra metadata about the subscription
latest_invoice?	subscription invoice object	The latest invoice for the subscription
use_storekit_resubscribe	boolean	Whether the subscription should be managed through StoreKit
price	?integer	The price of the subscription (only available for certain third-party subscriptions)
entitlements?	array[entitlement object]	The entitlements granted by the subscription

Partial Subscription Structure

Field	Type	Description
id	snowflake	The ID of the subscription
type	integer	The type of subscription
payment_gateway	?integer	The payment gateway used to bill the subscription
currency	string	The lower-cased ISO 4217 currency code the subscription is billed in
items	array[subscription item object]	The items in the subscription
payment_gateway_plan_id	?string	The payment gateway's plan ID for the subscription
payment_gateway_subscription_id?	?string	The payment gateway's subscription ID for the subscription
current_period_start	ISO8601 timestamp	When the current billing period started
current_period_end	ISO8601 timestamp	When the current billing period ends
streak_started_at?	ISO8601 timestamp	When the current subscription streak started

Subscription Type

Value	Name	Description
1	PREMIUM	Subscription is a Discord premium (Nitro) subscription
2	GUILD	Subscription is a guild role subscription
3	APPLICATION	Subscription is an application subscription

Subscription Status

Value	Name	Description
0	UNPAID	Subscription is unpaid
1	ACTIVE	Subscription is active
2	PAST_DUE	Subscription is past due
3	CANCELED	Subscription is canceled
4	ENDED	Subscription has ended
6	ACCOUNT_HOLD	Subscription is on account hold
7	BILLING_RETRY	Subscription failed to bill and will retry
8	PAUSED	Subscription is paused
9	PAUSE_PENDING	Subscription is pending pause

Subscription Item Structure

Field	Type	Description
id	snowflake	The ID of the subscription item
quantity	integer	How many of the items have been/are being purchased
plan_id	snowflake	The ID of the plan the item is for

Subscription Renewal Mutations Structure

Field	Type	Description
payment_gateway_plan_id?	?string	The payment gateway's new plan ID for the subscription
items?	array[subscription item object]	The new items of the subscription

Subscription Metadata Structure

Field	Type	Description
is_egs?	boolean	Whether the subscription was received from an Epic Games store trial
is_holiday_promotion_2021?	boolean	Whether the subscription was received from 2021 Holiday promotion
ended_at?	string	When the subscription ended
guild_id? (deprecated)	snowflake	The ID of the guild the subscription's entitlements apply to
application_subscription_guild_id?	snowflake	The ID of the guild the subscription's entitlements apply to
grace_period_expires_date?	ISO8601 timestamp	When the grace period expires
apple_grace_period_expires_date?	ISO8601 timestamp	When the grace period expires (only applicable for `APPLE` payment gateway)
google_grace_period_expires_date?	ISO8601 timestamp	When the grace period expires (only applicable for `GOOGLE` payment gateway)
google_original_expires_date?	string	When the subscription expires, disregarding the grace period (only applicable for `GOOGLE` payment gateway)
user_trial_offer_id?	snowflake	The ID of the user trial offer on the subscription
user_discount_offer_id?	snowflake	The ID of the user discount offer on the subscription
active_discount_id?	snowflake	The ID of the discount on the subscription
active_discount_expires_at?	ISO8601 timestamp	When the subscription discount expires

Subscription Trial Object

Subscription Trial Structure

Field	Type	Description
id	snowflake	The ID of the trial
interval	integer	The interval of the trial plan
interval_count	integer	The number of intervals included in the trial
sku_id	snowflake	The ID of the SKU the trial is for

Example Subscription Trial

{
  "id": "1073698058383917056",
  "interval": 3,
  "interval_count": 14,
  "sku_id": "521847234246082599"
}

Premium Guild Subscription Slot Object

Represents a premium guild subscription (boost) slot.

Premium Guild Subscription Slot Structure

Field	Type	Description
id	snowflake	The ID of the premium guild subscription slot
subscription_id	snowflake	The ID of the subscription
canceled	boolean	Whether the premium guild subscription slot was canceled
cooldown_ends_at	?string	When the cooldown for this premium guild subscription slot ends
premium_guild_subscription	?premium guild subscription object	The premium guild subscription, if the slot was already applied

Example Premium Guild Subscription Slot

{
  "id": "1315132642890350601",
  "subscription_id": "1315132642890350600",
  "canceled": false,
  "cooldown_ends_at": null,
  "premium_guild_subscription": {
    "id": "1315132642890350602",
    "user_id": "673658900435697665",
    "guild_id": "1081635484209520802",
    "ended": false,
    "pause_ends_at": null,
    "user": {
      "id": "673658900435697665",
      "username": "android",
      "global_name": "Android",
      "avatar": "08f104f8d5406c4d46916794fe2efeb7",
      "avatar_decoration_data": {
        "asset": "a_8552f9857793aed0cf816f370e2df3be",
        "sku_id": "1232071712695386162",
        "expires_at": null
      },
      "collectibles": null,
      "discriminator": "0",
      "public_flags": 4194560,
      "primary_guild": null
    }
  }
}

Endpoints

Get Subscriptions

GET/users/@me/billing/subscriptions

Returns a list of subscription objects.

Query String Params

Field	Type	Description
include_inactive?	boolean	Whether to include inactive subscriptions (default false)
limit?	integer	Max number of subscriptions to return (1-20, default unlimited)
exclude_unpaid_statuses?	boolean	Whether to exclude subscriptions of `UNPAID` status (default false)
subscription_type?	integer	Return only subscriptions with the specified type
sync_level?	integer	The sync level (default `NONE`)

User Lazy Perk Sync Level

Value	Name	Description
0	NONE	Do not resync anything
1	ADD_PERKS_IF_DETECTED	Add perks if detected
2	FULL_RESYNC	Fully resync perks

Get Subscription

GET/users/@me/billing/subscriptions/{subscription.id}

Returns a subscription object for the given subscription ID.

Create Subscription

POST/users/@me/billing/subscriptions

Creates a new subscription. Returns a subscription object on success. Fires a User Subscriptions Update and Payment Update Gateway event.

JSON Params

Field	Type	Description
items ¹	array[partial subscription item object]	The items in the subscription
payment_source_id?	snowflake	The ID of the payment source to pay with
payment_source_token?	?string	The token used to authorize with the payment source
return_url? ²	?string	TThe URL to redirect to after payment is complete (max 2048 characters)
currency?	string	The lower-cased ISO 4217 currency code
trial_id?	?snowflake	The ID of the trial to apply to the subscription
expected_invoice_price? ³	?expected price structure object	The expected price for the invoice in the smallest currency unit
expected_renewal_price? ³	?expected price structure object	The expected renewal price in the smallest currency unit
purchase_token ⁴	string	The purchase token of the payment client (max 1024 characters)
gateway_checkout_context?	?gateway checkout context object	The context for the gateway checkout, if applicable
code?	string	Unknown
metadata?	subscription metadata request object	Extra metadata about the subscription
load_id?	string	A client-generated UUID used to identify the current checkout session, used for purchase deduplication

¹ Only the plan_id field is required.

² If required, this URL is typically set to the Create Billing Popup Bridge Redirect endpoint with a response_type of success, which redirects the user back to the Discord client for handling.

³ If the actual amount charged does not match these expected values, the purchase will fail.

⁴ See the section on payment clients for more information.

Expected Price Structure

Field	Type	Description
currency	string	The lower-cased ISO 4217 currency code
amount	integer	The price amount in the smallest currency unit

Subscription Metadata Request Structure

Field	Type	Description
guild_id?	snowflake	The ID of the guild the subscription's entitlements will apply to

Modify Subscription

PATCH/users/@me/billing/subscriptions/{subscription.id}

Modifies a subscription. Returns the updated subscription object on success. Fires a User Subscriptions Update Gateway event.

Query String Params

Field	Type	Description
location?	string	The analytics location the request initiated from
location_stack?	string	The stack of analytics locations the request initiated from

JSON Params

Field	Type	Description
items? ¹	array[partial subscription item object]	The items in the subscription
payment_source_id?	snowflake	The ID of the payment source to pay with
payment_source_token?	string	The token used to authorize with the payment source
return_url? ²	?string	TThe URL to redirect to after payment is complete (max 2048 characters)
currency?	string	The lower-cased ISO 4217 currency code
status?	integer	The status of subscription
pause_duration?	integer	The duration to pause the subscription for, in days
expected_invoice_price? ³	?expected price structure object	The expected price for the invoice in the smallest currency unit
expected_renewal_price? ³	?expected price structure object	The expected renewal price in the smallest currency unit
purchase_token? ⁴	string	The purchase token of the payment client (max 1024 characters)
gateway_checkout_context?	?gateway checkout context object	The context for the gateway checkout, if applicable
load_id?	string	A client-generated UUID used to identify the current checkout session, used for purchase deduplication

¹ Only the plan_id field is required.

² If required, this URL is typically set to the Create Billing Popup Bridge Redirect endpoint with a response_type of success, which redirects the user back to the Discord client for handling.

³ If the actual amount charged does not match these expected values, the purchase will fail.

⁴ See the section on payment clients for more information.

Delete Subscription

DELETE/users/@me/billing/subscriptions/{subscription.id}

Deletes a subscription. Returns a 204 empty response on success. Fires a User Subscriptions Update Gateway event.

Query String Params

Field	Type	Description
location?	string	The analytics location the request initiated from
location_stack?	string	The stack of analytics locations the request initiated from

Create Subscription Preview

POST/users/@me/billing/subscriptions/preview

Previews a new subscription. Returns an invoice object on success.

JSON Params

Field	Type	Description
items ¹	array[partial subscription item object]	The items in the subscription
currency?	string	The lower-cased ISO 4217 currency code
payment_source_id?	?snowflake	The ID of the payment source to pay with
trial_id?	?snowflake	The ID of the trial to apply to the subscription
apply_entitlements?	boolean	Whether to apply entitlements (credits) to the previewed subscription
renewal?	boolean	Whether the previewed subscription should be a renewal
code?	string	Unknown
metadata?	map[string, any]	Extra metadata about the subscription

¹ Only the plan_id field is required.

Field	Type	Description
items? ¹	array[partial subscription item object]	The items the previewed invoice should have
payment_source_id?	snowflake	The ID of the payment source the previewed invoice should be paid with
currency?	string	The lower-cased ISO 4217 currency code
apply_entitlements?	boolean	Whether to apply entitlements (credits) to the previewed invoice
renewal?	boolean	Whether the previewed invoice should be a renewal
user_discount_offer_id?	snowflake	The ID of the discount offer to apply to the previewed invoice

¹ Only the plan_id field is required.

Field	Type	Description
payment_source_id	?snowflake	The ID of the payment source the invoice should be paid with
payment_source_token?	string	The token used to authorize with the payment source
currency?	string	The lower-cased ISO 4217 currency code to pay with
return_url?	string	The URL to return to after the payment is complete

Claim Subscription Promotion Reward

POST/users/@me/billing/subscriptions/{subscription.id}/promotion-reward

Claims a promotion reward from the given subscription.

Response Body

Field	Type	Description
eligible	boolean	Whether the subscription is eligible for the reward
reason	string	The reason whether the subscription is eligible
entitlement?	entitlement object	The granted reward entitlement

Subscription Promotion Reward Eligibility Reason

Value	Description
user_eligible_for_reward	User is eligible for reward
user_not_eligible_for_experiment	User is not eligible for relevant experiment

Get Premium Guild Subscription Cooldown

GET/users/@me/guilds/premium/subscriptions/cooldown

Returns the cooldown for premium guild subscription slot changes.

Response Body

Field	Type	Description
ends_at	ISO8601 timestamp	When the cooldown resets
limit	integer	The maximum number of changes that can be made before the cooldown is applied
remaining	integer	The number of changes remaining before the cooldown is applied

Get Applied Premium Guild Subscriptions

GET/users/@me/guilds/premium/subscriptions

Returns a list of premium guild subscription objects applied by the current user.

Query String Params

Field	Type	Description
paused?	boolean	Whether to return only paused premium guild subscriptions (default false)