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

FieldTypeDescription
idsnowflakeID of the subscription
user_idsnowflakeID of the user who is subscribed
sku_idsarray of snowflakesList of SKUs subscribed to
entitlement_idsarray of snowflakesList of entitlements granted for this subscription
renewal_sku_ids?array of snowflakesList of SKUs that this user will be subscribed to at renewal
current_period_startISO8601 timestampStart of the current subscription period
current_period_endISO8601 timestampEnd of the current subscription period
statusSubscriptionStatusCurrent status of the subscription
canceled_at?ISO8601 timestampWhen the subscription was canceled
country?stringISO3166-1 alpha-2 country code of the payment source used to purchase the subscription. Missing unless queried with a private OAuth scope.
The start of a subscription is determined by its ID. When the subscription renews, its current period is updated. If the user cancels the subscription, the subscription will enter the ENDING status and the canceled_at timestamp will reflect the time of the cancellation.

​
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 an indication of whether a user should have access to a specific SKU. See our guide on Implementing App Subscriptions for more information.
Subscriptions can start and change between any of these statuses within the current period. A subscription can be ACTIVE outside its current period or INACTIVE within its current period. Some examples of this behavior include:
  • While a failed payment is being retried, the subscription would remain ACTIVE until it succeeds or our system determines the payment is not recoverable.
  • A refund or chargeback during the current period would make 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

FieldTypeDescriptionDefault
before?snowflakeList subscriptions before this IDabsent
after?snowflakeList subscriptions after this IDabsent
limit?integerNumber of results to return (1-100)50
user_id?snowflakeUser ID for which to return subscriptions. Required except for OAuth queries.absent

​
Get SKU Subscription

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