Subscriptions guide

This guide is an in-depth walkthrough of building a subscription service with Stripe. You can also get a quick intro or check out the subscriptions API reference.


  1. Overview
  2. The lifecycle of a subscription
  3. Changing subscriptions
  4. Changing the amount billed
  5. Multiple subscriptions
  6. Examples and use cases


If you use subscriptions for your business, you can build anything from simple recurring billing to very complex relationships (using invoice items, discounts, quantities, trial periods, and multiple active subscriptions per customer).

A subscription is defined as the association of a customer with a plan.

Step 1: Create plans

To start, you’ll need to create a plan either via the API or through the dashboard. Plans have the following parameters:

  • id: a value to identify the plan to the API. Unlike other IDs that are auto-generated by Stripe, this ID is specified by you and must be unique across all the plans in your Stripe account.

  • name: a user-friendly label for the plan that’ll be seen by you in your dashboard, and possibly by your customers on receipts.

  • amount: what the customer will be charged per subscription per interval. For simple subscriptions, a customer might have a single subscription that costs $9.99/month. In more advanced uses of subscriptions, a customer might have 5 subscriptions to a single plan and would pay $49.95/month (e.g., 5 * $9.99).

  • interval: the billing period for the plan, which can range from a single day to a year. The interval options are day, week, month, or year. You can also use the interval_count to set more customized intervals, such as billing a customer every 30 days or every 5 months. If you’d like to test subscription behavior by creating a subscription that bills sooner than one day from its creation, one thing you can do is set a trial_end to some point in the near future via the API.

  • trial_period_days: An optional number used when working with trials.

To start, let’s assume you’ve created two plans:

  • Basic Monthly at $10/month (id: basic_monthly)
  • Premium Monthly at $25/month (id: premium_monthly)

Step 2: Subscribe customers

Having created one or more plans, you can now subscribe customers to plans. In order to bill customers for subscriptions, you’ll need to collect their payment details using Checkout or Stripe.js. (Even with subscriptions, you still need to securely obtain the customer’s payment information.)

Assuming you’ve used Checkout or Stripe.js to fetch a Stripe token that represents the customer’s payment information, you can then create a customer and subscribe her to a plan in one step:

The code above creates a customer, associates the previously provided payment info with that customer, and subscribes the customer to the “Basic Monthly” plan. (Note that the plan value should be its ID, not its name.)

Just as you would when attempting a charge, you should wrap that code within a try...catch block in order to handle any thrown exceptions. If the payment method was invalid (i.e., the customer’s card was declined), if the plan does not exist, or if anything else went wrong, you’ll need to handle the error.

If successful, the resulting Customer object will reflect that the customer was successfully subscribed to the plan. The default_card property will point to the default payment method. The subscriptions property will contain the subscription that you created.

You should store the id property in your database along with the other customer info that you’ve collected, such as login credentials, for later reference.

Step 3: Sync with your site

Subscriptions require more coordination between your site and Stripe than one-time payments do. Let’s use the example of a site where a subscription provides access to site content.

On your site, you’d need to store each user’s login credentials (e.g., username and password, in an appropriately secure, encrypted format). You’d also need to store a value for how long the customer has paid for access.

If a customer was subscribed to a monthly plan, you would initially set this timestamp value (i.e., active_until) to one month from now. When the customer logs in, you’d verify the login credentials and check the active_until timestamp to confirm that it’s still in the future, and therefore an active account.

TIP: You can view all active subscriptions from the dashboard. You can even filter by which customers are subscribed to a particular plan.

When the subscription is renewed (i.e., when Stripe bills the customer and they are charged again) your site will need to be notified of the additional payment so that you can update the customer’s active_until timestamp in your database. This is where events and webhooks come into play.

The lifecycle of a subscription

Beyond the simple act of subscribing a customer to a plan, everything you’ll want to do relative to subscriptions with Stripe requires an understanding the lifecycle of a subscription–and invoices.


Subscriptions on Stripe are charged through invoices. We generate an Invoice object that represents the amount the customer owes and then attempt to charge the customer that amount. Note that this kind of invoice isn’t actually sent to the customer but is instead paid automatically in Stripe. A successful payment of the invoice results in an active subscription.

When you first subscribe a customer to a plan, an invoice is immediately generated. Assuming that the plan does not have a free trial period (i.e., the customer must pay immediately), Stripe will immediately attempt to charge the customer for that invoice amount. The invoice is then closed, denoted by the closed parameter with the value of true.

Once an invoice is closed, it cannot be modified or have additional items added to it as the customer has already been charged. An invoice’s metadata can be updated at any time.

When a subscription period is up (e.g., one month or two weeks or whatever period your plan uses), Stripe will automatically generate another invoice. Unlike the first invoice, Stripe will wait approximately one hour before attempting to charge subsequent invoices so that you can make adjustments to the invoice if needed (e.g., add additional charges to the invoice, or add credits that offset the invoice amount). The invoice is considered open during this time, and its closed parameter has the value false.

In order to make adjustments to an invoice, your site will need to be aware of the invoice’s creation by using webhooks, which listen for events.

Subscription events

Stripe has an associated event for everything that happens with a subscription. (There’s actually dozens of events that occur when using Stripe, not all of which are specific to subscriptions.)

For our example of a new customer with a valid payment method and no trial period, this image shows the lifecycle of events.

When certain events occur, you should listen for the associated webhooks and take corresponding steps on your website (e.g., extending the length of time that a customer can use your site, or terminating access when a subscription is canceled). Note that the exact order in which you receive the events is not guaranteed.

Other important events can also occur, such as invoice.payment_failed. While these aren’t part of the normal cycle, you’ll still need to be set up to handle them.


Webhooks are a tool Stripe uses to notify your site of the events that occur related to your account. To use them, you’ll have to create an endpoint (e.g., a script) on your site that Stripe will send information to and register that endpoint with Stripe.

The webhook endpoint

We’ll send event data as JSON to your webhook endpoint. The specifics of the data will differ based upon the type of event that occurred.

Beyond whatever your endpoint does with the JSON data, it must also return a 200 status code to tell Stripe that the event notification was received. If your script does not return 200, Stripe will continue to retry the webhook until it’s properly acknowledged.

Here’s a simple webhook endpoint setup:

From that point, you can use the JSON data stored in event_json to take the necessary actions. Note that your webhooks resource will always automatically be notified of every event that occurs, and you’ll need to write your webhook endpoint to gracefully handle different–and unfamiliar–event types.

Working with JSON event data

The JSON data sent to your webhook depends on the type of event. Here’s a example response for an invoice.payment_succeeded event (edited for brevity):

  "created": 1326853478,
  "type": "invoice.payment_succeeded",
  "data": {
    "object": {
      "id": "in_00000000000000",
      "object": "invoice",
      "customer": "cus_00000000000000",

Every event will include a type property indicating the kind of event that took place. By looking at that value, you can figure out how to respond. Events often include the customer that the event is for, which you can use to match up with the customer records you’ve previously stored.

For events related to invoices, your webhook endpoint will receive the applicable plan, its details, the period to which the invoice applies (as Unix timestamps), and more.

Using this info, you can update your database (e.g., extend the active_until value), send an email (to yourself or the customer), or simply log the transaction.

Verifying events

As an extra security measure, you can verify an event with Stripe before acting upon it. Just use the event ID that your webhook received to directly retrieve the event details from Stripe:

If successful, the result of the retrieve call will be an Event object.

Registering Your Webhook Endpoint

With the webhook endpoint set up, you can register it with Stripe:

  1. Log in to your dashboard.
  2. Select your account name > Account Settings > Webhooks.
  3. Click Add URL and enter your webhook URL. Indicate whether this is for live or test transactions.
  4. Click Create webhook URL.

Once you register a webhook endpoint, Stripe will wait up to 72 hours for that endpoint to successfully receive the notification before attempting payment on an invoice.

Stripe will always attempt to pay an invoice except in certain situations:

  • If no valid payment information is stored for the customer, Stripe won’t attempt to pay the invoice.
  • If previous attempts have failed (and the account has been marked as unpaid), Stripe will continue to generate invoices but will not attempt to pay them.
  • If you’re using webhooks and Stripe does not see a successful response for the invoice.created event, Stripe will continue retrying the webhook every hour for up to 72 hours. During that time, no payment will be attempted until a successful response is received.

If the webhook hasn’t succeeded after 72 hours, Stripe will attempt to pay the invoice. Along the way, you’ll also get an email notifying you that the webhook is failing.

As new ideas are introduced in the rest of the guide, the corresponding events will be mentioned. It’s up to your webhooks to recognize these events and react accordingly. For example, you’ll want to mark a customer as inactive in your database when the customer.subscription.deleted event occurs.

Changing subscriptions

There’s several ways that a subscription can change:

Working with trials

Subscriptions can begin with a free trial period in one of two ways:

  1. Defining a trial in the plan itself
  2. Setting a trial period when subscribing the customer to a plan by passing a trial_end timestamp

To do the latter, set a trial_end value (Unix timestamp in seconds) when creating the customer.

When you define a plan with a trial period, every new customer subscribed to that plan will automatically receive that free trial period. The number of trial days a customer has used is tracked on a per-subscription basis. We will deduct the number of trial days previously consumed by a customer from the plan’s trial_period_days and use the remaining days, if any, for the trial. If you’d like to change the length of that trial period, you can use the code above to override it. Providing the value “now” for trial_end will enroll the customer to a subscription without a trial period.

Three days before the trial period is up, a customer.subscription.trial_will_end event will be sent to your webhook endpoint. If you’d like, you can use it as a trigger to email your customer that billing for the plan is about to begin.

Once the trial period is up, Stripe will generate an invoice and send out an invoice.created event notification. Approximately an hour later, Stripe will attempt to charge that invoice. Assuming that the payment attempt succeeded, you’ll receive notifications of the following events:

  • charge.succeeded
  • invoice.payment_succeeded
  • customer.subscription.updated (reflecting an update from a trial to an active subscription)

To make a subscription active without waiting for the trial period to end, you can use the update subscription API call, setting the trial_end value to “now”:

Upgrading or downgrading plans

Subscriptions can be changed by switching the plan to which a customer is subscribed. Normally this is a matter of either upgrading or downgrading the subscription, depending upon the price difference between the two plans.

Assuming a customer is currently subscribed to the basic_monthly at $10 per month, here’s how you’d switch the customer to the premium_monthly plan:

If both plans have the same billing frequency (e.g., interval and interval_count), the customer will retain the same billing dates. If the plans don’t have the same billing frequency, the new plan will be billed at the new interval, starting on the day of the change. For example, if you switch a customer from one monthly plan to another, the billing date does not change. However, if you switch a customer from a monthly plan to a yearly plan, the billing date becomes the date of the switch.

If the subscription change moves the customer from no-pay being required to a paid requirement (e.g., from a trial period to an active subscription, or from a free plan to a paid plan) or moves the customer to a different billing frequency (e.g., yearly to monthly), Stripe will synchronously attempt payment of the amount owed. In other words, in these cases, Stripe will attempt payment as part of the subscription change request. If that payment succeeds, the subscription update request will also succeed. But if that payment fails, the subscription change request will also fail, and the subscription will be left unchanged.

The most confusing aspect to upgrading or downgrading plans is how existing payments are factored into the amount to be invoiced. By default, Stripe prorates subscription costs.

For example, say the customer in the above code is billed on the 1st of each month and the above code is executed exactly half-way through the plan’s billing cycle (i.e., on the 15th of March). In that case, the customer has already paid $10, and used half of the current billing cycle. When the customer is switched to the new plan, with a cost of $25, the unused portion of the previous plan results in a credit of $5. The cost of the new plan for the rest of the billing cycle (i.e., the rest of March) will be $12.50. Therefore, the total prorated cost of switching from the cheaper plan to the most expensive plan is $7.50. This amount will be added to the next invoice.

The next invoice, on April 1st, will also reflect the payment required on the new plan for that upcoming month: $25. Thus, the April 1st invoice would be for a total of $32.50.

Note that changing the plan would not change the billing cycle in this example. The customer will not be billed the $32.50 at the time when the plans are switched. The plan changes impact the next invoice, which remains on the same billing cycle (as both plans have the same billing frequency).

If the new plan is less expensive than the existing plan, the prorated credit will be larger than the new amount due. For example, if the customer is switching from the $25/month plan to the $10/month plan exactly halfway through the billing cycle, the customer will have a net credit of $7.50 resulting from a credit of $12.50 for the unused portion of the old plan less a charge of $5 for the remaining time on the new plan. The next invoice, at the start of the next billing period, will reflect the $7.50 credit and the $10 due for a full, upcoming month on the new plan, resulting in a net charge of of $2.50.

The prorated amount is calculated down to the second by Stripe. This means that Stripe will calculate the differences between the two plans based on the time that the API call was made to change the customer’s plan, using the current billing period’s start and end times.

To preview the cost of a proration before changing the customer’s subscription, you can use the upcoming invoice API. This will show what the customer’s next invoice will look like if the change to their subscription is applied. The first two invoice items will be the prorations created during the update. (If a subscription goes from a paid subscription to a trial, only the negative proration will be created, instead of two prorations.)

Because Stripe prorates to the second, the amount of the prorations can change slightly between the time they are previewed, and the time the update is actually done. To avoid this problem, you can “lock in” the proration amount by passing in a subscription_proration_date (on an invoice) or proration_date parameter (on a subscription), which will cause the proration to be calculated as though the proration was done at that time.

One approach to locking in the proration date is to specify the timestamp as a hidden form field on the preview page shown to customers. This will get submitted to your server when they submit the form, and you can pass this value through to the subscription update API. It’s a good idea to make sure that the proration date value submitted with the form is from the last 10 minutes or so, to prevent the price from being affected too much. The length of the lock-in period will vary depending on what you think is appropriate for your business. It’s also a good idea to make sure this value isn’t in the future, since this would only happen if the customer tampers with their form.

Prorating the costs of plans is the default behavior. You can disable proration by setting prorate to false when making a subscription change:

With proration disabled, the customer will be billed the full amount for the new plan when the next invoice is generated.

If you want the customer to immediately pay the price difference when switching plans, you’ll need to generate an invoice after making the switch (explained below).

Note that changing a plan will trigger a customer.subscription.updated event, among other possible events.

Holding a renewal for review

Rather than automatically charging the customer for the invoice items at the end of a billing period, you can hold the invoice for a review process. Close the invoice within one hour of receiving the invoice.created event—this will prevent Stripe from automatically charging your customer for the invoice amount.

Once you’ve reviewed the invoice and are ready to charge the customer, you can reopen the invoice and then pay the invoice.

Canceling subscriptions

Subscriptions are also changed when they’re canceled:

By default, the cancellation takes effect immediately. Once a customer’s subscription is canceled, no further invoices will be generated for that subscription. If the customer had paid for the entire billing period and the subscription was canceled part-way through the period, the customer is not credited a refund automatically by Stripe.

If you would like to cancel the subscription immediately, but keep the subscription active until the end of the billing period (e.g., through the time the customer has already paid for), provide an at_period_end value of true:

  • Stripe sends out a customer.subscription.deleted event when a customer’s subscription is canceled immediately.
  • A customer.subscription.updated event is immediately triggered if you cancel a subscription at the end of the billing period instead, reflecting the change in the subscription’s cancel_at_period_end value. When the subscription is actually canceled at the end of the period, a customer.subscription.deleted event will occur.

Reactivating canceled subscriptions

If a customer’s subscription has been canceled with at_period_end set to true and it has not yet reached the end of the billing period, update the subscription and set the plan to the same ID as the current plan. This updates the subscription’s cancel_at_period_end to false and prevents the subscription from canceling at the end of the billing period. You can also use the Reactivate Subscription option from the Dashboard.

If the cancelation has already been processed and the subscription is no longer active, a new subscription is needed for the customer. Keep in mind that Stripe immediately starts your customer’s subscription under a new billing cycle, so this result in a new charge. You can override this behavior by using the trial_end parameter so the customer isn’t immediately billed (e.g., to maintain the old billing cycle).

Payment failures

A subscription also changes if an invoice is generated but the charge attempt fails. The events that occur and the results of those events when a charge attempt fails depend upon your subscription account settings.

In the Stripe dashboard, under Account Settings > Subscriptions, you can choose how Stripe should respond when an invoice payment attempt fails. Stripe can retry failed payments up to four times, and you can specify the delay between attempts.

You can also decide whether the subscription’s status should be marked as unpaid or canceled after the last payment attempt fails. (Note that a payment failure on the very first invoice of a subscription without a trial results in the customer never being subscribed to the plan.)

In either case, after the final payment attempt on an invoice, no further payment attempts will be made until a new payment method (i.e., credit card) is added to the customer’s account. The two states differ in what happens from that point forward.

  • With a canceled subscription, the unpaid invoice will be closed, and no further invoices will be generated. A customer.subscription.deleted event is triggered, following the charge.failed and invoice.payment_failed events that would have preceded it. Since the subscription is fully deleted at this point, there is no direct way to “reactivate” it. If you collect updated billing details from your customer, you can “start from scratch”: update your customer’s default card and add the customer to a new subscription.

  • If you choose to mark the subscription as unpaid, it will continue to generate new invoices, but those invoices will be marked as closed. This prevents subsequent payment attempts, which would fail.

  • If you choose to leave the subscription as-is, it will continue to generate new invoices, and those new invoices will be attempted. You can use this if you want to keep attempting to bill your customers every month, even when previous invoice payments have failed.

Note that when a subscription has been scheduled for cancellation using at_period_end, it can be reactivated at any point up to the end of the period with any update via the API or the dashboard.

TIP: When an invoice payment fails, the customer gets flagged as “delinquent”, letting you easily identify delinquent customers using filters in the dashboard. The delinquent property always represents whether the most recent payment attempt succeeded or failed. When that invoice is paid, the delinquent label is removed.

A subscription will be reactivated when the most recently created unpaid invoice for the subscription is paid. So, if it is June 15th, but the May 1st and June 1st invoices are both unpaid:

  • Successfully paying the May 1st invoice will not reactivate the subscription.
  • Successfully paying the June 1st invoice will reactivate the subscription.

Changing the amount billed

The amount a customer is billed on a subscription (via an invoice) is based upon the plan’s cost. Switching between plans usually affects the amount invoiced, due to proration. There are also other ways you can change the amount billed on any given invoice:

In many cases, more than one of these options can have the same net effect, but philosophically preferring one over the other will make more sense.

Adding invoice items

Invoice items are the most common way to change the amount the customer will be charged. Invoice items appear on an invoice as separate line items.

Invoice items are always added to the next invoice to be charged. For example, if a customer is billed on the 1st of each month, any invoice item generated during the month is added to the invoice generated on the 1st of the following month.

As another example, when Stripe automatically generates an invoice for a recurring payment, your site will be notified of the invoice via webhooks (an invoice.created event). Stripe will wait approximately an hour before attempting to pay that invoice. In that time, you can add invoice items to the recently-created invoice.

You can create an invoice item at any point in time, and you can create as many invoice items as you want:

Should you need to include a one-time charge or discount to the first subscription invoice, you can do so by adding an invoice item to the customer before creating the subscription. Simply use the above code but omit the invoice parameter. The created invoice item will be attached to the customer and automatically included in the first invoice created.

Any positive invoice item amount (an integer in cents) increases the cost of the applicable invoice. To discount an invoice, use a negative amount.

Invoice items have some unique behaviors:

  • Invoice items will always be charged when the billing period ends even if the subscription is canceled. Canceling a customer’s subscription only means the customer will not be billed again if no invoice items exist.
  • Invoice items are not prorated when a customer’s subscription is changed from one plan to another.

Using customer balances

Account balances are simply a way to directly set how much a customer owes or is owed. You can establish an account balance when you create the customer:

The amount needs to be an integer in cents. Like invoice items, customer account balances will automatically be factored into the next invoice. A positive amount as a customer balance increases the amount of the next invoice. A negative amount becomes a credit that decreases the amount of the next invoice.

You can also set the account balance by updating a customer:

Account balances are easy to implement and understand–and they don’t impact one-off charges. The main downside to manipulating amounts charged via account balances is that they don’t provide a way to document the adjustment, as you can using the description on an invoice item or by applying a discount.

Applying discounts

Coupons are used to provide discounts to a customer on recurring charges. A coupon will reduce the amount of an invoice (by either a percentage of the total of all invoice items, or a flat amount). To start, you’ll need to create the coupon, which can be done in the dashboard or via the API. Coupons have the following parameters:

  • percent_off or amount_off
  • currency
  • duration: either once, forever, or repeating. When using repeating, also specify duration_in_months: the number of months for which the coupon should repeatedly apply.
  • id: a unique identifier that serves as the “code” for the coupon.
  • max_redemptions: the total number of times that this coupon can be applied to customers. For example, you can restrict a coupon to the first 50 customers that use it, or you can make a coupon expire by a certain date.
  • redeem_by: the latest date at which this coupon can be applied to customers.

The maximum number of redemptions and the expiration date apply to every customer you have. If you do the latter, this only impacts when the coupon can be applied to a customer. If you set a coupon to last forever when used by a customer, but have it expire on January 1st, any customer given that coupon will have that coupon’s discount forever, but no new customers can apply the coupon after January 1st.

TIP: Coupons can be designed to work once (e.g., apply to one invoice), apply to a number of months regardless of the billing period in use, or to last forever. The duration settings individually impact each customer, based on the time that the coupon was applied to the customer.

Coupons can be applied to a customer when the customer is created:

Coupons can also be added to existing customers by updating the customer:

If you delete a coupon, customers that already have discounts that were created using the coupon will keep those discounts, but no new redemptions of the coupon will be allowed.

Setting quantities

The final way to change the amount billed to a customer is to use quantities. Quantities are often used to have your subscriptions reflect either multiple simultaneous purchases or to easily support multiple payment amounts.

By default, each subscription is to one instance of a plan, but Stripe does allow you to subscribe a customer to multiple quantities of a plan to flexibly adjust the amount billed each period.

For example, say you run a hosting company through which a customer may host 5 sites at a cost of $9.99 per month. You could create a plan for $49.95 and subscribe the customer to it. But then you would also need $9.99, $19.98, and other plans. Furthermore, the billing of $49.95 for 5 hosted sites would not be easily distinguished from your customers on your deluxe hosting plan at a cost of $49.95. The solution is to subscribe your customer to 5 of the $9.99 plan.

As another example, if the amount each customer pays can vary greatly, you could end up with too many plans to address all possible cases, and yet still need to create new plans for new situations. Alternatively, you could create a $1 plan and subscribe each customer to the appropriate quantity, thereby creating virtual $5 plans, $8 plans, $17 plans, and so forth.

To set the quantity of a plan, provide that argument and value when creating or updating the subscription:

Multiple quantities of a plan are billed using one invoice, and are prorated when subscriptions are changed, including when you change just the quantities involved.

Multiple subscriptions

Creating a new subscription

Stripe offers the ability to subscribe a single customer object to multiple subscriptions. Each subscription will have a unique ID and its state is handled independently from other subscriptions. To add a new subscription to an existing customer, first retrieve the customer, and then use the create method within the subscriptions sublist:

A customer can be subscribed to a single plan more than once. The billing cycle for each subscription can be different, and is dependent on when that subscription was created.

Note that the number of trial days a customer has used is tracked on a per-subscription basis. We will deduct the number of trial days previously consumed by a subscription from the plan’s trial_period_days unless a trial_end value is specified.

Discounting a subscription

A coupon can be applied directly to the customer object, or on the subscription itself. A coupon applied at the customer object level will be applied to all recurring charges for that customer. However, a coupon applied at the subscription level will always take priority. An invoice can only have one coupon applied–it’s not possible to stack two or more coupons onto an invoice.

Specific examples and use cases

Generating invoices

At the end of a billing cycle, Stripe will automatically create an invoice containing both a line item for the customer’s subscription and any invoice items that had been left pending on the customer. However, when the customer has pending invoice items, you can also request that an invoice be generated at any time. Generating a one-off invoice will not affect the customer’s standard billing schedule, but it will pull in any pending invoice items.

You can do this via the API using the create invoice method or from the dashboard, using the “Invoice Now” button in the Pending Invoice Items pane.

This can be helpful when you want to request immediate payment of prorations that were created when you upgraded your customer’s subscription (e.g., upgrading a user from a $10 per month plan to a $20 per month plan mid-month will trigger proration invoice items in the net of approximately $5). However, by default, these prorations will simply remain pending on the customer until the end of the month. If you’d like the customer to be billed immediately, you can always request creation of an invoice after upgrading.

Note that creating an invoice does not lead to an synchronous attempt to pay the invoice. However, the invoice will be automatically attempted between and 1 and 2 hours after it is created. You can also request immediate payment of an invoice at any time using pay_invoice.

Varying billing amounts

Some users need full flexibility in computing billing amounts. For example, you might have a conceptual subscription that has a base cost of $10 per month, and a $5 per-seat cost each month. We recommend representing these billing relationships by creating a base plan that is only $1 per month, or even $0.01 per month. This lets you use quantity parameter to bill each user very flexibly. In an example with a $10 base cost and three $5 seats, you could use a $1 per month base plan, and set quantity=25 to achieve the desired total cost of $25 for the month.

Creating an installment plan

Stripe does not currently have direct support for installment plans (i.e., “3 easy payments of $19.99”). However, you can easily set up an installment plan on top of our subscriptions. Essentially, if you want to bill a customer for three payments of $19.99:

  • Subscribe the customer to a $19.99 per month plan. The first payment will occur immediately when the signup occurs.
  • Every time you get an invoice.paid webhook for the user, you can increment a counter on your side to track the total amount paid by the customer.
  • After the third successful payment, you can cancel the customer’s subscription.

Changing or deleting plans

Once a plan has been created, only the metadata and statement description can be modified—the billing amount or interval cannot. Should any changes to these parameters be needed, a new plan must be created instead. This avoids the potential surprise of changing the amount that existing users are billed, and the confusion of having some customers on different price points with the same plan.

If you only want to subscribe new customers to the new plan price, create a new plan. This makes it clearer which customers are subscribed to each plan, as each plan’s ID is different.

To switch all your customers over to the new plan pricing, update each existing customer’s subscription to the new plan. To prorate the plan switch, update the existing subscription using the API. Depending on the new plan, this may reset the billing cycle.

If you’d rather charge customers the full amount of the new plan, cancel their subscriptions before subscribing them to the new plan]. This resets the customer’s billing cycle.

Deleting a plan does not affect any existing subscribers of that plan, but new customers cannot be subscribed to it.

Changing the billing cycle

If you’re looking to change the billing date on a plan, we recommend specifying a new trial_end when you want to update the billing date of an existing subscription. For example, if it is May 15th and a customer has an active subscription that is set to bill next on May 23rd, but you set their trial_end to be June 1st:

  • The customer will not be billed on May 23rd.
  • The customer will be billed next on June 1st, and then will subsequently be billed on the first of the month thereafter.

If you’re just needing to update the billing cycle of an existing subscription, make sure to also set prorate to false so that the customer is not credited for any unused time on their plan.

You can also set the trial_end parameter for an existing subscription within the Dashboard. Head to the customer with the subscription that you wish to edit, then set the subscription’s Trial end. Similar to above, be sure to uncheck the Prorate fee option so the customer isn’t credited.

Pausing a subscription

If you want to suspend a subscription and resume it at a later date, simply cancel the customer’s subscription so that no further billing will take place. When the customer is ready to resume their subscription, reactivate the canceled subscription, making sure that the trial period is set to end on the day their billing should resume.

Working with local currencies

A plan’s currency is set at the time of plan creation. If you’d like to offer the same plan in multiple currencies, you’d have to create separate plans.

Likewise, customer objects are tethered to the currency in which you first charge them. If a customer subscribes to a plan denominated in USD but would later like to be billed in GBP, you wouldn’t be able to subscribe her to a plan in a different currency as she’s already denominated as a USD customer. In this case, you would have to create an entirely new customer object.

Accepting alternative payment methods

Stripe accepts payments using several alternative methods, including: Bitcoin, Alipay, and ACH. Of these, Bitcoin cannot be used for subscriptions, but Alipay and ACH can. With Alipay, you must generate a reusable Alipay token for subscription use. With ACH, no special steps are required, but:

  • As with all ACH payments, it takes up to 5 business days to receive confirmation of the payment’s success or failure
  • If an ACH payment on a subscription fails, the subscription will automatically move to its final state per your settings (e.g., the subscription will be marked as unpaid or canceled)

Next up

Congrats! You’ve gone through how to set up subscriptions with Stripe. Some things you might want to see next: