Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Overview
Online payments
Products and prices
Invoicing
Subscriptions
    Overview
    How subscriptions work
    Recurring pricing models
    Get started
    Quickstart
    Integrate a SaaS business
    Embed a pricing table
    Design an integration
    Build a subscriptions integration
    Migrate subscriptions to Stripe
    Billing resources
    Coupons
    Customers
    Subscriptions
    Subscription invoices
    Manage subscriptions
    Change subscriptions
      Upgrade and downgrade subscriptions
      Cancel subscriptions
      Manage prorations
      Pause payment collection
      Share an update payment details link
      Manage pending updates
      Set billing cycles
      Customer credit balance
    Usage-based billing
    Use trial periods
    Set payment methods
    Subscriptions with multiple products
    Set subscription quantities
    Subscription webhooks
    Schedule subscriptions
    Tax
    Sales-led B2B billing
    Integrate with Salesforce
    Manage recurring revenue
    Revenue recognition
    Revenue recovery
    Subscription metrics
    Customer management
    Overview
    Set up the the no-code customer portal
    Set up the customer portal with the API
    Configure the customer portal
    Testing
    Test your integration
    Test clocks
    Strong Customer Authentication (SCA)
    Invoices API updates
Quotes
In-person payments
Multiparty payments
After the payment
Add payment methods
Payment Links
Stripe Checkout
Stripe Elements
About the APIs
Regulation support
Implementation guides
Testing
Billing
·
HomePaymentsSubscriptionsChange subscriptions

Setting the subscription billing cycle date

Learn how to set the billing date for subscriptions.

A subscription’s billing date is determined by two factors:

  • Its billing cycle anchor: This defaults to when the subscription was created—or, if you’re using a trial period, to the trial end. You can also explicitly set it at the subscription’s creation.
  • The recurring interval of its price or prices.

Billing cycle anchors are UNIX timestamps in seconds from the current epoch.

For example, a customer with a monthly subscription set to cycle on the 2nd of the month will always be billed on the 2nd.

If a month doesn’t have the anchor day, the subscription will be billed on the last day of the month. For example, a subscription starting on January 31 bills on February 28 (or February 29 in a leap year), then March 31, April 30, and so on.

Specifying the billing cycle anchor when creating new subscriptions

When creating new subscriptions, you can configure their billing cycle anchor to fixed dates (for example, the 1st of the next month).

To create a subscription with a billing cycle anchor in the future and a prorated invoice until the anchor, perform a create subscription call with a timestamp for billing_cycle_anchor:

Command Line
curl https://api.stripe.com/v1/subscriptions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d customer=
{{CUSTOMER_ID}}
\ -d "items[0][price]"=
{{PRICE_ID}}
\ -d billing_cycle_anchor=1611008505

You can also combine trials with billing_cycle_anchor, resulting in a free period followed by a prorated period.

When combining prorations with billing_cycle_anchor, the proration_behavior flag determines whether the customer receives a prorated invoice at all. If proration_behavior is none, the initial period up to the billing cycle anchor will be free—similar to a free trial. Unlike a trial, there is no 0 USD invoice.

Changing the billing cycle on pre-existing subscriptions

You can change when an existing subscription is billed in two ways:

  1. Reset the anchor to the current time using billing_cycle_anchor=now. Be aware that this results in the customer being invoiced immediately. You can do this through the API.
  2. Introducing a trial results in setting the anchor to the end of the trial. Trials are typically used at the start of a subscription. Applying them during a subscription is allowed. You can change a subscription’s billing cycle using a trial through the API or the Dashboard.

Make sure to consider prorating changes before getting started.

Prorating changes

Stripe bills subscriptions with conventional fixed-rate prices and per-seat prices in advance: the customer paid for the current recurring interval on the previous invoice.

The proration_behavior flag determines whether the customer receives a credit for the unused time from the previous invoice. When proration_behavior is none, changing the subscription causes no proration adjustments to be created.

  • When resetting billing_cycle_anchor, the customer is invoiced immediately for the next period. With proration disabled there is no credit for the unused time, so the new invoice for the full period amount might result in overpayment. Enabling proration in this case will result in the total invoiced amount being correct.

  • When moving the billing cycle using a trial, if you don’t want this period to be free (since the user is presumably continuing full access to your service or product), it’s important that you disable proration, so the customer isn’t credited for the now “free” period. Because trials are free parts of a subscription, introducing a trial to an existing paid subscription results in a proration. The customer receives a credit for the period they’ve already paid, because it’s free.

Setting the cycle to now through the API

To reset the billing cycle anchor, update the subscription with billing_cycle_anchor set to now:

Command Line
curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d billing_cycle_anchor=now \ -d proration_behavior=create_prorations

With this approach, you most likely want the default behavior of setting proration_behavior to create_prorations—as in the code sample—so the customer isn’t overcharged for unused time in the previous cycle.

Using a trial to change the billing cycle

By introducing a non-prorated trial period to a subscription, you can configure the billing cycle to be any date.

For example, if it’s May 15 and a customer has an active subscription set to bill next on May 23, and you introduce a trial period until June 1:

  • The customer won’t be billed on May 23.
  • The customer will be billed next on June 1, then on July 1, and so forth.

Changing the billing cycle through the API

To add a trial period to an existing subscription, perform an update subscription call, providing a trial_end value:

Command Line
curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d trial_end=1611008505 \ -d proration_behavior=none

As a reminder, set proration_behavior to none—as in the above code—so the customer isn’t credited for previously paid, but unused time.

Thresholds

In addition to the regular cycle, you can configure subscriptions to bill whenever the amount due reaches a threshold. If a subscription is configured to invoice this way, hitting the threshold can optionally reset the subscription cycle.

See billing thresholds for more details.

Changing the billing cycle with a trial through the Dashboard

To add a trial period to an existing subscription using the Dashboard:

  1. Find the subscription you want to change.
  2. Click Actions.
  3. Click Update subscription.
  4. Click Add trial and enter the number of days the trial should last.
  5. Click Update subscription.

Metered billing

With metered billing, the price paid by the customer varies based on consumption during the billing cycle. When changing the billing cycle results in ending a subscription interval early, you charge the customer for the usage accrued during the shortened billing cycle.

See also

  • Using trial periods
  • Update Subscription
Was this page helpful?
Questions? Contact Sales.
Need help? Contact Support.
Watch our developer tutorials.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Specifying the billing cycle anchor when creating new subscriptions
Changing the billing cycle on pre-existing subscriptions
Using a trial to change the billing cycle
Changing the billing cycle through the API
Thresholds
Changing the billing cycle with a trial through the Dashboard
Metered billing
See also
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to your Stripe account and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$