Skip to main content
Subscriptions in Discord represent a 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

​
id
snowflake
required
ID of the subscription. The start of a subscription is determined by its ID.
​
user_id
snowflake
required
ID of the user who is subscribed.
​
sku_ids
array of snowflakes
required
List of SKUs subscribed to.
​
entitlement_ids
array of snowflakes
required
List of entitlements granted for this subscription.
​
renewal_sku_ids
?array of snowflakes
required
List of SKUs that this user will be subscribed to at renewal. null if the subscription will not renew.
​
current_period_start
ISO8601 timestamp
required
Start of the current subscription period.
​
current_period_end
ISO8601 timestamp
required
End of the current subscription period. When the subscription renews, its current period is updated.
​
status
integer
required
Current status of the subscription.
​
canceled_at
?ISO8601 timestamp
required
When the subscription was canceled. Set when a user cancels, causing the subscription to enter the ENDING status.
​
country
string
ISO 3166-1 alpha-2 country code of the payment source used to purchase the subscription. Missing unless queried with a private OAuth scope. Optional field.

​
Subscription example

{
  "id": "1278078770116427839",
  "user_id": "1088605110638227537",
  "sku_ids": ["1158857122189168803"],
  "entitlement_ids": [],
  "renewal_sku_ids": null,
  "current_period_start": "2024-08-27T19:48:44.406602+00:00",
  "current_period_end": "2024-09-27T19:48:44.406602+00:00",
  "status": 0,
  "canceled_at": null
}

​
Subscription statuses

TypeValueDescription
ACTIVE0Subscription is active and scheduled to renew.
ENDING1Subscription is active but will not renew.
INACTIVE2Subscription is inactive and not being charged.
Subscription status should not be used to grant perks. Use entitlements as the indicator of whether a user should have access to a specific SKU. See the guide on Implementing App Subscriptions for more information.
Subscriptions can transition between any of these statuses within the current period. A subscription can be ACTIVE outside its current period or INACTIVE within its current period. Examples:
  • While a failed payment is being retried, the subscription remains ACTIVE until it succeeds or the payment is determined to be unrecoverable.
  • A refund or chargeback during the current period makes the subscription INACTIVE.

​
List SKU subscriptions

GET /skus/{sku.id}/subscriptions
Returns all subscriptions containing the SKU, filtered by user. Returns a list of subscription objects.

​
Query string params

​
before
snowflake
List subscriptions before this ID.
​
after
snowflake
List subscriptions after this ID.
​
limit
integer
default:"50"
Number of results to return (1–100).
​
user_id
snowflake
User ID for which to return subscriptions. Required except for OAuth queries.

​
Get SKU subscription

GET /skus/{sku.id}/subscriptions/{subscription.id}
Get a subscription by its ID. Returns a subscription object.