A valid request URL is required to generate request examples{
"id": "<string>",
"object": "subscription",
"customer": "<string>",
"status": "incomplete",
"collection_method": "charge_automatically",
"items": [
{
"id": "<string>",
"price": "<string>",
"quantity": 123,
"metadata": {}
}
],
"current_period_start": 123,
"current_period_end": 123,
"billing_cycle_anchor": 123,
"cancel_at_period_end": true,
"metadata": {},
"livemode": true,
"test_clock": "<string>",
"created_at": 123,
"updated_at": 123,
"default_payment_method": "<string>",
"trial_start": 123,
"trial_end": 123,
"canceled_at": 123,
"ended_at": 123,
"latest_invoice": "<string>"
}{
"error": {
"code": "INVALID_DATA",
"message": "invalid collection_method"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "SUBSCRIPTION_NOT_FOUND",
"message": "subscription not found"
}
}{
"error": {
"code": "CONFLICT",
"message": "subscription modified concurrently, please retry"
}
}{
"error": {
"code": "INVALID_SUBSCRIPTION_STATE",
"message": "invalid subscription state for this operation"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Cancel a subscription
Cancels the subscription. Pass at_period_end: true to let the
current period run out before canceling; omit it or pass false to
cancel immediately. An immediately-canceled subscription transitions to
canceled; a period-end cancellation sets cancel_at_period_end: true
and the status remains unchanged until the period ends. The request
body is optional.
A valid request URL is required to generate request examples{
"id": "<string>",
"object": "subscription",
"customer": "<string>",
"status": "incomplete",
"collection_method": "charge_automatically",
"items": [
{
"id": "<string>",
"price": "<string>",
"quantity": 123,
"metadata": {}
}
],
"current_period_start": 123,
"current_period_end": 123,
"billing_cycle_anchor": 123,
"cancel_at_period_end": true,
"metadata": {},
"livemode": true,
"test_clock": "<string>",
"created_at": 123,
"updated_at": 123,
"default_payment_method": "<string>",
"trial_start": 123,
"trial_end": 123,
"canceled_at": 123,
"ended_at": 123,
"latest_invoice": "<string>"
}{
"error": {
"code": "INVALID_DATA",
"message": "invalid collection_method"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "SUBSCRIPTION_NOT_FOUND",
"message": "subscription not found"
}
}{
"error": {
"code": "CONFLICT",
"message": "subscription modified concurrently, please retry"
}
}{
"error": {
"code": "INVALID_SUBSCRIPTION_STATE",
"message": "invalid subscription state for this operation"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Authorizations
A merchant secret key (sk_…) sent as Authorization: Bearer <key>.
Headers
Merchant ID when an authorized Platform acts for a connected Merchant. Omit when authenticating directly as that Merchant.
^mer_[0-9A-Za-z]{14}$A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.
255Path Parameters
The subscription id (sub_…).
Body
Response
The updated subscription.
Unique identifier for the subscription (sub_…).
subscription Customer id (cus_…).
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.
incomplete, trialing, active, past_due, unpaid, canceled One of charge_automatically (charged automatically against the default payment method) or send_invoice (the buyer pays each invoice through the hosted invoice page).
charge_automatically, send_invoice The recurring prices and quantities the subscription bills.
Show child attributes
Show child attributes
Unix epoch seconds. Start of the current billing period.
Unix epoch seconds. End of the current billing period.
Unix epoch seconds. The reference point used to compute period boundaries.
True when the subscription is scheduled to cancel at the end of the current period.
Custom key-value pairs for your use.
Show child attributes
Show child attributes
The logical billing clock inherited from the customer; null when the subscription uses wall-clock time.
Unix epoch seconds.
Unix epoch seconds when the subscription was last updated.
The payment method used for automatic renewal charges (pm_…). Null when not set.
Unix epoch seconds. Start of the trial period. Null when the subscription was not created with a trial.
Unix epoch seconds. End of the trial period. Null when no trial.
Unix epoch seconds. When the cancellation was requested. Null while not canceled.
Unix epoch seconds. When the subscription terminated. Null while active.
Most recent invoice id (inv_…). Null before the first invoice is issued.