Skip to main content
A Subscription object represents an ongoing billing relationship where a customer is charged on a recurring basis. Subscriptions are created when a customer purchases a subscription Product and manage the lifecycle of recurring Payments. Subscriptions track billing intervals, status changes, and link to all associated Payments and Orders. You can use the API to manage subscriptions including updating, pausing, and cancelling them.

​
Endpoints

​
Ending a trial early

A subscription in trialing status can be converted to a paid subscription right away with the endTrial endpoint. The first invoice is created and charged immediately using the payment method on file, and the outcome (emails, webhooks, orders) is identical to the trial ending naturally. The request fails with a 400 if the subscription is not trialing or has no payment method saved.

​
Multiple line items

The create, update, and charge endpoints accept an items array with up to 20 line items, so a single subscription can bill several offers together (e.g. a package plus add-ons) while the invoice and webhook payloads keep the full per-line breakdown. Because one subscription maps to a single Stripe subscription, all items must be on the same cadence:
  • Same currency — every item resolves to the same currency (either explicitly or from its offer).
  • Same billing interval — every offer shares the same interval and interval_count. Mixing, for example, a monthly and a yearly offer is rejected with a 400 rather than failing at Stripe.
  • No trial — a trial is only applied to single-item subscriptions; multi-item subscriptions start billing immediately.
  • No discount codes — discount codes are not supported when a subscription has more than one item.
Requests that violate these rules return a 400 with a descriptive message.

​
The Subscription object

​
object
string
Object type identifier. Always "subscription" for Subscription objects.
​
id
string
required
Subscription identifier, based on the initial order number.
​
status
string
required
Current subscription status. Possible values: active, past_due, canceled, unpaid, incomplete, incomplete_expired, trialing, paused
​
createdAt
integer | null
Unix timestamp (milliseconds) when the subscription was created.
​
currentIntervalStart
integer | null
Unix timestamp (milliseconds) when the current billing interval started.
​
currentIntervalEnd
integer | null
Unix timestamp (milliseconds) when the current billing interval ends.
​
cancelAtIntervalEnd
boolean
Whether the subscription will cancel at the end of the current interval. Defaults to false.
​
canceledAt
integer | null
Unix timestamp (milliseconds) when the subscription was cancelled, if applicable.
​
userId
string | null
UUID of the subscribed User.
​
user
User | null
Expanded User object with basic subscriber information.
​
orderId
string
required
UUID of the initial Order that created this subscription.
​
orderNumber
string
required
Human-readable number of the initial order.
​
order
Order
required
Expanded Order object for the initial subscription order.
​
lastPaymentId
string | null
UUID of the most recent Payment for this subscription.
​
lastPaymentNumber
string | null
Human-readable number of the most recent payment.
​
lastPayment
Payment | null
Expanded Payment object for the most recent charge.

​
Subscription lifecycle

​
Example response

​
Webhook events

See Event types and Webhooks overview for why subscription_created can include PENDING payments and why you should not rely on it alone for access grants.

Payments

Payment transactions for subscriptions

Orders

Initial orders creating subscriptions

Users

Subscribed customers

Events

Subscription webhook events