Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key
string

A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.

Maximum string length: 255

Path Parameters

id
string
required

The subscription id (sub_…).

Body

application/json
at_period_end
boolean

When true, the subscription runs until the end of the current period before canceling. Defaults to false (immediate cancellation).

reason
string

Optional cancellation reason.

Response

The updated subscription.

id
string
required
object
enum<string>
required
Available options:
subscription
customer
string
required

Customer id (cus_…).

status
enum<string>
required

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.

Available options:
incomplete,
trialing,
active,
past_due,
unpaid,
canceled
collection_method
enum<string>
required
Available options:
charge_automatically,
send_invoice
items
object[]
required
current_period_start
integer
required

Unix epoch seconds. Start of the current billing period.

current_period_end
integer
required

Unix epoch seconds. End of the current billing period.

billing_cycle_anchor
integer
required

Unix epoch seconds. The reference point used to compute period boundaries.

cancel_at_period_end
boolean
required

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

metadata
object
required
livemode
boolean
required
created_at
integer
required

Unix epoch seconds.

updated_at
integer
required
default_payment_method
string | null

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

trial_start
integer | null

Unix epoch seconds. Start of the trial period. Null when the subscription was not created with a trial.

trial_end
integer | null

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

canceled_at
integer | null

Unix epoch seconds. When the cancellation was requested. Null while not canceled.

ended_at
integer | null

Unix epoch seconds. When the subscription terminated. Null while active.

latest_invoice
string | null

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