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
collection_method
enum<string>
required
Available options:
charge_automatically,
send_invoice

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.