Subscriptions

Learn how to use the subscription resource with Stripe Billing.

Subscriptions are a core resource in Stripe. They represent what your customer is paying for and how much and how often you’re charging them for the product. You build and manage subscriptions by using other core Stripe resources, like Customers, Products, Prices, and Invoices, and PaymentIntents.

You can create and update subscriptions from the Dashboard or the API. Use the API if you have a large number of subscriptions to manage, or if you want to manage them programmatically.

You can subscribe customers:

Manually through the Dashboard
With Payment Links
Programmatically through the API
Through your website by embedding pricing tables and linking to a Checkout session

Manage how you notify customers about different subscription events in the subscriptions email settings page of the Dashboard.

Create a subscription

To create a subscription, combine a recurring price with a customer. To bundle one-time purchases with a recurring purchase, you can do so by using add_invoice_items:

Command Line

curl https://api.stripe.com/v1/subscriptions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d customer={{CUSTOMER_ID}} \
  -d "items[0][price]"="{{RECURRING_PRICE_ID}}" \
  -d "add_invoice_items[0][price]"="{{ONE_TIME_PRICE_ID}}"

This creates a 10 USD per month subscription for the prices analytics dashboard and charges a one-time setup fee of 20 USD. The customer is charged 30 USD for their first month and then 10 USD each month after that.

You can also use add_invoice_items when updating subscriptions, including pending updates. All invoice items configured in add_invoice_items are created immediately. If the update results in an invoice, the invoice includes the invoice items. Otherwise, the invoice items remain pending on the customer and the next invoice picks them up. If your business charges additional fees when upgrading to a new service, pass the price for that fee in add_invoice_items.

Use subscription schedules

Some customers want to schedule their analytics dashboard service to start in the future or only sign up for a year of service at a time. Subscription schedules allow you to configure phases with a recurring price to start in the future or end on a particular date. If you want to bundle one-time purchases with the beginning of a phase, you can do so by using add_invoice_items on a phase:

Command Line

curl https://api.stripe.com/v1/subscription_schedules \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d customer="{{CUSTOMER_ID}}" \
  -d start_date=1680307200 \
  -d "phases[0][items][0][price]={{RECURRING_PRICE_ID}}" \
  -d "phases[0][add_invoice_items][0][price]={{PRICE_ID}}"

This schedules a 10 USD per month subscription to begin in the future and its first invoice will include a one-time fee of 20 USD. If you configure add_invoice_items on future phases, invoice items won’t be generated until that phase begins. If you set add_invoice_items on the current phase, invoice items are generated immediately.

Subscriptions

Create a subscription

Use subscription schedules

See also