# Subscription Resource

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

| Field                  | Type                                                                                | Description                                                                                                                                |
| ---------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| id                     | snowflake                                                                           | ID of the subscription                                                                                                                     |
| user\_id               | snowflake                                                                           | ID of the user who is subscribed                                                                                                           |
| sku\_ids               | array of snowflakes                                                                 | List of SKUs subscribed to                                                                                                                 |
| entitlement\_ids       | array of snowflakes                                                                 | List of entitlements granted for this subscription                                                                                         |
| renewal\_sku\_ids      | ?array of snowflakes                                                                | List of SKUs that this user will be subscribed to at renewal                                                                               |
| current\_period\_start | ISO8601 timestamp                                                                   | Start of the current subscription period                                                                                                   |
| current\_period\_end   | ISO8601 timestamp                                                                   | End of the current subscription period                                                                                                     |
| status                 | [SubscriptionStatus](/guides/http-api-resources-subscription#subscription-statuses) | Current [status](/guides/http-api-resources-subscription#subscription-statuses) of the subscription                                        |
| canceled\_at           | ?ISO8601 timestamp                                                                  | When the subscription was canceled                                                                                                         |
| country?               | string                                                                              | ISO3166-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

```json
{
  "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

| Type     | Value | Description                                     |
| -------- | ----- | ----------------------------------------------- |
| ACTIVE   | 0     | Subscription is active and scheduled to renew.  |
| INACTIVE | 1     | Subscription is inactive and not being charged. |
| ENDING   | 2     | Subscription is active but will not renew.      |

:::callout{intent="info"}
Subscription status should not be used to grant perks. Use [entitlements](/guides/http-api-resources-entitlement#entitlement-object) as an indication of whether a user should have access to a specific SKU. See our guide on [Implementing App Subscriptions](/guides/monetization-2-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

/skus/[{sku.id}](/guides/http-api-resources-sku#sku-object)/subscriptions

Returns all subscriptions containing the SKU, filtered by user. Returns a list of [subscription](/guides/http-api-resources-subscription#subscription-object) objects.

### Query String Params

| Field     | Type      | Description                                                                   | Default |
| --------- | --------- | ----------------------------------------------------------------------------- | ------- |
| before?   | snowflake | List subscriptions before this ID                                             | absent  |
| after?    | snowflake | List subscriptions after this ID                                              | absent  |
| limit?    | integer   | Number of results to return (1-100)                                           | 50      |
| user\_id? | snowflake | User ID for which to return subscriptions. Required except for OAuth queries. | absent  |

## Get SKU Subscription

/skus/[{sku.id}](/guides/http-api-resources-sku#sku-object)/subscriptions/[{subscription.id}](/guides/http-api-resources-subscription#subscription-object)

Get a subscription by its ID. Returns a [subscription](/guides/http-api-resources-subscription#subscription-object) object.

## Related pages

- [API Reference](./api-reference-index.md)
- [App Fundamentals](./app-fundamentals-index.md)
- [Best Practices](./best-practices-index.md)
- [Bots & Companion Apps](./bots-companion-apps-index.md)
- [Building Games](./building-games-index.md)
- [Building on Discord](./building-on-discord-index.md)
- [Change Log](./change-log-index.md)
- [Communities & Servers](./communities-servers-index.md)
- [Components](./components-index.md)
- [Core Concepts](./core-concepts-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.