> ## Documentation Index
> Fetch the complete documentation index at: https://discord-markm-docs-lobby-membership-disconnect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Resource

> Reference for Discord subscription objects that represent recurring payments.

export const Route = ({method, children}) => {
  return <div className="MDXRoute">
      <span className={"verb" + " " + method.toLowerCase()}>{method}</span>
      <span className="url">{children}</span>
    </div>;
};

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](/developers/resources/subscription#subscription-statuses) | Current [status](/developers/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 theme={null}
{
  "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. |

<Info>
  Subscription status should not be used to grant perks. Use [entitlements](/developers/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](/developers/monetization/implementing-app-subscriptions) for more information.
</Info>

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

<Route method="GET">/skus/[\{sku.id}](/developers/resources/sku#sku-object)/subscriptions</Route>

Returns all subscriptions containing the SKU, filtered by user. Returns a list of [subscription](/developers/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

<Route method="GET">/skus/[\{sku.id}](/developers/resources/sku#sku-object)/subscriptions/[\{subscription.id}](/developers/resources/subscription#subscription-object)</Route>

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