Subscriptions

Subscriptions allow you to charge a customer on a recurring basis.

Related guide: Creating subscriptions

Was this section helpful? Yes No

Create a subscription

POST / v1 / subscriptions

Update a subscription

POST / v1 / subscriptions /:id

Retrieve a subscription

GET / v1 / subscriptions /:id

List subscriptions

GET / v1 / subscriptions

Cancel a subscription

DELETE / v1 / subscriptions /:id

Migrate a subscription

POST / v1 / subscriptions /:id / migrate

Resume a subscription

POST / v1 / subscriptions /:id / resume

Search subscriptions

GET / v1 / subscriptions / search

The Subscription object

Attributes

id string Unique identifier for the object.
automatic _ tax object Automatic tax settings for this subscription.
currency enum Three-letter ISO currency code, in lowercase. Must be a supported currency.
customer string Expandable ID of the customer who owns the subscription.
customer _ account nullable string ID of the account representing the customer who owns the subscription.
default _ payment _ method nullable string Expandable ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over default_source. If neither are set, invoices will use the customer’s invoice_settings.default_payment_method or default_source.
description nullable string The subscription’s description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs. The maximum length is 500 characters.
items object List of subscription items, each with an attached price.
latest _ invoice nullable string Expandable The most recent invoice this subscription has generated over its lifecycle (for example, when it cycles or is updated).
metadata map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
pending _ setup _ intent nullable string Expandable You can use this SetupIntent to collect user authentication when creating a subscription without immediate payment or updating a subscription’s payment method, allowing you to optimize for off-session payments. Learn more in the SCA Migration Guide.
pending _ update nullable object If specified, pending updates that will be applied to the subscription once the latest_invoice has been paid.
status enum Possible values are incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid, or paused. For collection_method=charge_automatically a subscription moves into incomplete if the initial payment attempt fails. A subscription in this status can only have metadata and default_source updated. Once the first invoice is paid, the subscription moves into an active status. If the first invoice is not paid within 23 hours, the subscription transitions to incomplete_expired. This is a terminal status, the open invoice will be voided and no further invoices will be generated. A subscription that is currently in a trial period is trialing and moves to active when the trial period is over. A subscription can only enter a paused status when a trial ends without a payment method. A paused subscription doesn’t generate invoices and can be resumed after your customer adds their payment method. The paused status is different from pausing collection, which still generates invoices and leaves the subscription’s status unchanged. If subscription collection_method=charge_automatically, it becomes past_due when payment is required but cannot be paid (due to failed payment or awaiting additional user actions). Once Stripe has exhausted all payment retry attempts, the subscription will become canceled or unpaid (depending on your subscriptions settings). If subscription collection_method=send_invoice it becomes past_due when its invoice is not paid by the due date, and canceled or unpaid if it is still not paid by an additional deadline after that. Note that when a subscription has a status of unpaid, no subsequent invoices will be attempted (invoices will be created, but then immediately automatically closed). After receiving updated payment information from a customer, you may choose to reopen and pay their closed invoices.

More attributes

object string, value is "subscription"
application nullable string Expandable Connect only
application _ fee _ percent nullable number Connect only
billing _ cycle _ anchor timestamp
billing _ cycle _ anchor _ config nullable object
billing _ mode object
billing _ schedules array of objects
billing _ thresholds nullable object
cancel _ at nullable timestamp
cancel _ at _ period _ end boolean
canceled _ at nullable timestamp
cancellation _ details nullable object
collection _ method enum
created timestamp
days _ until _ due nullable integer
default _ source nullable string Expandable
default _ tax _ rates nullable array of objects
discounts array of strings Expandable
ended _ at nullable timestamp
invoice _ settings object
livemode boolean
managed _ payments nullable object
next _ pending _ invoice _ item _ invoice nullable timestamp
on _ behalf _ of nullable string Expandable Connect only
pause _ collection nullable object
payment _ settings nullable object
pending _ invoice _ item _ interval nullable object
presentment _ details nullable object
schedule nullable string Expandable
start _ date timestamp
test _ clock nullable string Expandable
transfer _ data nullable object Connect only
trial _ end nullable timestamp
trial _ settings nullable object
trial _ start nullable timestamp

The Subscription object

{ "id": "sub_1MowQVLkdIwHu7ixeRlqHVzs", "object": "subscription", "application": null, "application_fee_percent": null, "automatic_tax": { "enabled": false, "liability": null }, "billing_cycle_anchor": 1679609767, "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "cancellation_details": { "comment": null, "feedback": null, "reason": null }, "collection_method": "charge_automatically", "created": 1679609767, "currency": "usd", "customer": "cus_Na6dX7aXxi11N4", "days_until_due": null, "default_payment_method": null, "default_source": null, "default_tax_rates": [], "description": null, "discounts": null, "ended_at": null, "invoice_settings": { "issuer": { "type": "self" } }, "items": { "object": "list", "data": [ { "id": "si_Na6dzxczY5fwHx", "object": "subscription_item", "created": 1679609768, "current_period_end": 1682288167, "current_period_start": 1679609767, "metadata": {}, "plan": { "id": "price_1MowQULkdIwHu7ixraBm864M", "object": "plan", "active": true, "amount": 1000, "amount_decimal": "1000", "billing_scheme": "per_unit", "created": 1679609766, "currency": "usd", "discounts": null, "interval": "month", "interval_count": 1, "livemode": false, "metadata": {}, "nickname": null, "product": "prod_Na6dGcTsmU0I4R", "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1MowQULkdIwHu7ixraBm864M", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1679609766, "currency": "usd", "custom_unit_amount": null, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "product": "prod_Na6dGcTsmU0I4R", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tax_behavior": "unspecified", "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 1000, "unit_amount_decimal": "1000" }, "quantity": 1, "subscription": "sub_1MowQVLkdIwHu7ixeRlqHVzs", "tax_rates": [] } ], "has_more": false, "total_count": 1, "url": "/v1/subscription_items?subscription=sub_1MowQVLkdIwHu7ixeRlqHVzs" }, "latest_invoice": "in_1MowQWLkdIwHu7ixuzkSPfKd", "livemode": false, "metadata": {}, "next_pending_invoice_item_invoice": null, "on_behalf_of": null, "pause_collection": null, "payment_settings": { "payment_method_options": null, "payment_method_types": null, "save_default_payment_method": "off" }, "pending_invoice_item_interval": null, "pending_setup_intent": null, "pending_update": null, "schedule": null, "start_date": 1679609767, "status": "active", "test_clock": null, "transfer_data": null, "trial_end": null, "trial_settings": { "end_behavior": { "missing_payment_method": "create_invoice" } }, "trial_start": null}

Create a subscription

POST / v1 / subscriptions

Creates a new subscription on an existing customer. Each customer can have up to 500 active or scheduled subscriptions.

When you create a subscription with collection_method=charge_automatically, the first invoice is finalized as part of the request. The payment_behavior parameter determines the exact behavior of the initial payment.

To start subscriptions where the first invoice always begins in a draft status, use subscription schedules instead. Schedules provide the flexibility to model more complex billing configurations that change over time.

Parameters

automatic _ tax object Automatic tax settings for this subscription.
currency enum Three-letter ISO currency code, in lowercase. Must be a supported currency.
customer string The identifier of the customer to subscribe.
customer _ account string The identifier of the account representing the customer to subscribe.
default _ payment _ method string ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over default_source. If neither are set, invoices will use the customer’s invoice_settings.default_payment_method or default_source.
description string The subscription’s description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs. The maximum length is 500 characters.
items array of objects Required A list of up to 20 subscription items, each with an attached price.
metadata map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
payment _ behavior enum Controls how Stripe handles the first invoice when payment is required and collection_method=charge_automatically. Subscriptions with collection_method=send_invoice are automatically activated regardless of the first Invoice status. Possible enum values allow_incomplete This is the default behavior since 2019-03-14. If payment fails, the Subscription is created with status=incomplete, otherwise status=active. This behavior allows you to manage scenarios where additional customer actions are needed to pay the Invoice. For example, SCA regulations might require 3DS authentication to complete payment. See the SCA Migration Guide for Billing to learn more. default_incomplete When the first invoice requires payment, creates a Subscription with status=incomplete without attempting payment, otherwise status=active. You must request explicit confirmation of the Invoice’s PaymentIntent to activate the subscription. The resulting Invoice has auto_advance=false, so Stripe doesn’t automatically attempt payment, retry payment, or finalize the subscription. error_if_incomplete If payment fails, return an HTTP 402 status code and don’t create the subscription. This behavior doesn’t support payments that require user action, such as 3DS authentication, because it returns an error instead of creating a PaymentIntent with status=requires_action. To handle payments that require action, use allow_incomplete or default_incomplete instead. This behavior was the default for API versions before 2019-03-14. pending_if_incomplete This behavior is exclusive to Subscription updates and cannot be used for creation.

More parameters

add _ invoice _ items array of objects
application _ fee _ percent number Connect only
backdate _ start _ date timestamp
billing _ cycle _ anchor timestamp
billing _ cycle _ anchor _ config object
billing _ mode object
billing _ schedules array of objects
billing _ thresholds object
cancel _ at timestamp | enum
cancel _ at _ period _ end boolean
collection _ method enum
days _ until _ due integer
default _ source string
default _ tax _ rates array of strings
discounts array of objects
invoice _ settings object
off _ session boolean
on _ behalf _ of string
payment _ settings object
pending _ invoice _ item _ interval object
proration _ behavior enum
transfer _ data object Connect only
trial _ end string, value is "now" | timestamp
trial _ from _ plan boolean
trial _ period _ days integer
trial _ settings object

Returns

The newly created Subscription object, if the call succeeded. If the attempted charge fails, the subscription is created in an incomplete status.

Response

{ "id": "sub_1MowQVLkdIwHu7ixeRlqHVzs", "object": "subscription", "application": null, "application_fee_percent": null, "automatic_tax": { "enabled": false, "liability": null }, "billing_cycle_anchor": 1679609767, "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "cancellation_details": { "comment": null, "feedback": null, "reason": null }, "collection_method": "charge_automatically", "created": 1679609767, "currency": "usd", "customer": "cus_Na6dX7aXxi11N4", "days_until_due": null, "default_payment_method": null, "default_source": null, "default_tax_rates": [], "description": null, "discounts": null, "ended_at": null, "invoice_settings": { "issuer": { "type": "self" } }, "items": { "object": "list", "data": [ { "id": "si_Na6dzxczY5fwHx", "object": "subscription_item", "created": 1679609768, "current_period_end": 1682288167, "current_period_start": 1679609767, "metadata": {}, "plan": { "id": "price_1MowQULkdIwHu7ixraBm864M", "object": "plan", "active": true, "amount": 1000, "amount_decimal": "1000", "billing_scheme": "per_unit", "created": 1679609766, "currency": "usd", "discounts": null, "interval": "month", "interval_count": 1, "livemode": false, "metadata": {}, "nickname": null, "product": "prod_Na6dGcTsmU0I4R", "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1MowQULkdIwHu7ixraBm864M", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1679609766, "currency": "usd", "custom_unit_amount": null, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "product": "prod_Na6dGcTsmU0I4R", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tax_behavior": "unspecified", "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 1000, "unit_amount_decimal": "1000" }, "quantity": 1, "subscription": "sub_1MowQVLkdIwHu7ixeRlqHVzs", "tax_rates": [] } ], "has_more": false, "total_count": 1, "url": "/v1/subscription_items?subscription=sub_1MowQVLkdIwHu7ixeRlqHVzs" }, "latest_invoice": "in_1MowQWLkdIwHu7ixuzkSPfKd", "livemode": false, "metadata": {}, "next_pending_invoice_item_invoice": null, "on_behalf_of": null, "pause_collection": null, "payment_settings": { "payment_method_options": null, "payment_method_types": null, "save_default_payment_method": "off" }, "pending_invoice_item_interval": null, "pending_setup_intent": null, "pending_update": null, "schedule": null, "start_date": 1679609767, "status": "active", "test_clock": null, "transfer_data": null, "trial_end": null, "trial_settings": { "end_behavior": { "missing_payment_method": "create_invoice" } }, "trial_start": null}