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": "CUSTOMER_NOT_FOUND",
"message": "customer not found"
}
}{
"error": {
"code": "INVALID_SUBSCRIPTION_STATE",
"message": "invalid subscription state for this operation"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Create a subscription
Creates a subscription for a customer with one or more recurring-price
items. All items must share one currency and one billing cadence. An
initial invoice is issued immediately unless the subscription opens
with a trial. A charge_automatically subscription that starts with
a trial requires a default_payment_method; the trial-end charge uses
it. If the customer has a test clock, the subscription automatically
inherits that clock and uses its frozen time for the first period.
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": "CUSTOMER_NOT_FOUND",
"message": "customer not found"
}
}{
"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.
255Body
Customer id (cus_…).
The recurring prices and quantities to bill.
Show child attributes
Show child attributes
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 Payment method id (pm_…). Required for charge_automatically subscriptions that start with a trial.
Unix epoch seconds. Start of the trial period. Defaults to the creation time when trial_end is set.
Unix epoch seconds. End of the trial period. No initial invoice is issued while the subscription is trialing.
Custom key-value pairs for your use.
Show child attributes
Show child attributes
Response
The created 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.