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": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Update default payment method
Sets or clears the default payment method used for charge_automatically renewal invoices. Pass null for default_payment_method to clear it.
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": "<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
Payment method id (pm_…). Pass null to clear the default.
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.