The subscription object

{
  "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
}

A Subscription (sub_…) attaches one or more priced items to a customer and bills them automatically each period. Each item references a recurring price from the catalog, and all items share one currency and one billing cadence. Your server creates and manages subscriptions. See Subscriptions for the full flow. A first invoice 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.

Attributes

string

Unique identifier for the subscription (sub_…).

string

Customer id (cus_…).

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.

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).

string | null

The payment method used for automatic renewal charges (pm_…). Null when not set.

array of objects

The recurring prices and quantities the subscription bills.

integer

Unix epoch seconds. Start of the current billing period.

integer

Unix epoch seconds. End of the current billing period.

integer | null

Unix epoch seconds. End of the trial period. Null when no trial.

boolean

True when the subscription is scheduled to cancel at the end of the current period.

string | null

Most recent invoice id (inv_…). Null before the first invoice is issued.

See every field in the response of Retrieve a subscription.

Endpoints

Endpoint	Use it for
Create a subscription	Start recurring billing for a customer.
List subscriptions	Review subscriptions, optionally filtered by status.
Retrieve a subscription	Check the current status, period, and latest invoice.
Check subscription entitlement	Decide whether the customer currently has access.
Cancel a subscription	Cancel immediately or at the end of the current period.
Resume a subscription	Reverse a period-end cancellation that has not yet taken effect.
Update subscription items	Change the items on a subscription.
Update collection method	Switch between `charge_automatically` and `send_invoice`.
Update default payment method	Set the payment method used for automatic renewal charges.
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.
A subscription whose customer is on a test clock carries that clock in test_clock.

Fundamentals

Payments

Checkout

In-person payments

Customers and catalog

Connect

Billing

Webhooks

The subscription object

Attributes

Endpoints

Statuses

Notes

​Attributes

​Endpoints

​Statuses

​Notes

Attributes

Endpoints

Statuses

Notes