> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The subscription object

> Bill a customer for recurring prices each period.

<ResponseExample>
  ```json The subscription object theme={null}
  {
    "id": "sub_01JEXAMPLE2K8V4N9C6M1Q7R",
    "object": "subscription",
    "customer": "cus_01JEXAMPLE2K8V4N9C6M1Q7R",
    "status": "incomplete",
    "collection_method": "charge_automatically",
    "default_payment_method": null,
    "items": [],
    "current_period_start": 1767225600,
    "current_period_end": 1767225600,
    "trial_end": null,
    "cancel_at_period_end": false,
    "latest_invoice": null,
    "livemode": false
  }
  ```
</ResponseExample>

A Subscription (`sub_…`) attaches one or more priced items to a [customer](/api-reference/customers)
and bills them automatically each period. Each item references a recurring price from the
[catalog](/api-reference/catalog), and all items share one currency and one billing cadence.
Your server creates and manages subscriptions. See [Subscriptions](/guides/subscriptions) for the full flow.

A first [invoice](/api-reference/invoices) is issued at creation, unless the subscription opens with a trial.
Later invoices are issued at each period boundary. Platforms can create and manage billing for connected
accounts: see [Billing for connected accounts](/guides/connect-billing).

## Attributes

<ResponseField name="id" type="string">
  Unique identifier for the subscription (`sub_…`).
</ResponseField>

<ResponseField name="customer" type="string">
  Customer id (`cus_…`).
</ResponseField>

<ResponseField name="status" type="string">
  `incomplete`: created; first invoice not yet paid. `trialing`: in free trial; no invoice yet (or a zero-total one). `active`: most recent invoice paid; in good standing. `past_due`: most recent invoice payment failed; in dunning. `unpaid`: dunning exhausted; service stopped. Terminal. `canceled`: terminated (immediately or at period end). Terminal.
</ResponseField>

<ResponseField name="collection_method" type="string">
  One of `charge_automatically` (charged automatically against the default payment method) or `send_invoice` (the buyer pays each invoice through the hosted invoice page).
</ResponseField>

<ResponseField name="default_payment_method" type="string | null">
  The payment method used for automatic renewal charges (`pm_…`). Null when not set.
</ResponseField>

<ResponseField name="items" type="array of objects">
  The recurring prices and quantities the subscription bills.
</ResponseField>

<ResponseField name="current_period_start" type="integer">
  Unix epoch seconds. Start of the current billing period.
</ResponseField>

<ResponseField name="current_period_end" type="integer">
  Unix epoch seconds. End of the current billing period.
</ResponseField>

<ResponseField name="trial_end" type="integer | null">
  Unix epoch seconds. End of the trial period. Null when no trial.
</ResponseField>

<ResponseField name="cancel_at_period_end" type="boolean">
  True when the subscription is scheduled to cancel at the end of the current period.
</ResponseField>

<ResponseField name="latest_invoice" type="string | null">
  Most recent invoice id (`inv_…`). Null before the first invoice is issued.
</ResponseField>

See every field in the response of [Retrieve a subscription](/api-reference/subscriptions/retrieve-a-subscription).

## Endpoints

| Endpoint | Use it for |
| - | - |
| [Create a subscription](/api-reference/subscriptions/create-a-subscription) | Start recurring billing for a customer. |
| [List subscriptions](/api-reference/subscriptions/list-subscriptions) | Review subscriptions, optionally filtered by status. |
| [Retrieve a subscription](/api-reference/subscriptions/retrieve-a-subscription) | Check the current status, period, and latest invoice. |
| [Check subscription entitlement](/api-reference/subscriptions/check-subscription-entitlement) | Decide whether the customer currently has access. |
| [Cancel a subscription](/api-reference/subscriptions/cancel-a-subscription) | Cancel immediately or at the end of the current period. |
| [Resume a subscription](/api-reference/subscriptions/resume-a-subscription) | Reverse a period-end cancellation that has not yet taken effect. |
| [Update subscription items](/api-reference/subscriptions/update-subscription-items) | Change the items on a subscription. |
| [Update collection method](/api-reference/subscriptions/update-collection-method) | Switch between `charge_automatically` and `send_invoice`. |
| [Update default payment method](/api-reference/subscriptions/update-default-payment-method) | Set the payment method used for automatic renewal charges. |
| [Update metadata](/api-reference/subscriptions/update-metadata) | Store your own key-value data on the subscription. |

## Statuses

| Status | Meaning |
| - | - |
| `incomplete` | Created; the first invoice is not yet paid. |
| `trialing` | In a free trial; no invoice yet, or a zero-total one. |
| `active` | The most recent invoice is paid. The subscription is in good standing. |
| `past_due` | The most recent invoice payment failed and the subscription is in dunning. |
| `unpaid` | Dunning is exhausted and service has stopped. Terminal. |
| `canceled` | Terminated, immediately or at period end. Terminal. |

## Notes

* Gate access on the `entitled` field from the entitlement endpoint. `access_until` is informational only and
  can be in the past or null while `entitled` is true, for example during an automatic payment retry.
* A period-end cancellation sets `cancel_at_period_end: true`. The status does not change until the period ends.
* An operation the subscription's state does not allow, such as canceling an already-canceled subscription,
  returns `422`.
* Mutating endpoints accept an optional `Idempotency-Key` header. See [Idempotency](/api-reference/idempotency).
* A subscription whose customer is on a [test clock](/api-reference/test-clocks) carries that clock in `test_clock`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.