Set the subscription billing renewal date

A subscription’s billing period depends on two factors:

• The recurring interval of its price or prices, such as monthly, yearly, weekly, and so on.
• The billing cycle anchor is the reference point that aligns future billing period dates. It sets the day of week for week intervals, the day of month for month and year intervals, and the month of year for year intervals. The default value is either the subscription creation date or the trial end date (if you’re using a trial period). You can also explicitly set this value at the time you create the subscription.

The following are examples of monthly subscriptions with different billing periods:

• A monthly subscription with a billing cycle anchor date of September 2 always bills on the 2nd day of the month.
• A monthly subscription with a billing cycle anchor date of January 31 bills the last day of the month closest to the anchor date, so February 28 (or February 29 in a leap year), then March 31, April 30, and so on.
• A weekly subscription with a billing cycle anchor date of Friday, June 3 bills every Friday thereafter.

Full billing periods start on the first full invoice date, which is often the same as the billing cycle anchor and is always interval-aligned with it.

Specify the billing cycle anchor for new subscriptions

There are two ways to set the billing cycle anchor on new subscriptions:

• Use billing_cycle_anchor_config to calculate the timestamp for you (monthly or yearly subscriptions only).
• Use billing_cycle_anchor to accept the timestamp directly.

If you’re creating a monthly or yearly subscription, we recommend using the billing_cycle_anchor_config parameter because it automatically factors in short months and leap years for you. If you’re creating a daily or weekly subscription, or if you prefer to set the renewal date of your subscription using a timestamp, use the billing_cycle_anchor parameter directly.

Use billing_cycle_anchor_config

To create an integration with monthly and yearly subscriptions, use billing_cycle_anchor_config on create subscription to specify the day of the month on which to anchor.

Set day_of_month to 31 to create a monthly subscription that renews at the end of the month, even in months with less than 31 days. If a month has less than 31 days, the subscription renews on the last day of that month.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "items[0][price]"=
{{PRICE_ID}} \
  -d "billing_cycle_anchor_config[day_of_month]"=31

You can also specify month to control the month of year for the anchor on multi-month and yearly subscriptions.

To cycle your yearly subscriptions on the first of July, create a yearly subscription with a month of 7 and day_of_month of 1.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "items[0][price]"=
{{PRICE_ID}} \
  -d "billing_cycle_anchor_config[month]"=7 \
  -d "billing_cycle_anchor_config[day_of_month]"=1

You can specify the exact month, day, hour, minute, and second for the billing cycle anchor by using billing_cycle_anchor_config. If you don’t specify the hour, minute, and second, they default to the values of the subscription creation time.

The billing cycle anchor uses Coordinated Universal Time (UTC). For example, if you create a subscription using billing_cycle_anchor_config at 5 PM EST without specifying the hour, the time is recorded in the system as 10 PM UTC.

billing_cycle_anchor_config doesn’t support anchoring on a backdated start date.

For example, if you have an existing monthly subscription with a billing_cycle_anchor timestamp that contains the day of the month, hour, minute, and second of 15, 12, 30, and 0, you can align a new monthly subscription with it. To do this, set day_of_month, hour, minute, and second to match those same values, respectively.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "items[0][price]"=
{{PRICE_ID}} \
  -d "billing_cycle_anchor_config[day_of_month]"=15 \
  -d "billing_cycle_anchor_config[hour]"=12 \
  -d "billing_cycle_anchor_config[minute]"=30 \
  -d "billing_cycle_anchor_config[second]"=0

If you use billing_cycle_anchor_config, it might result in a billing_cycle_anchor that’s more than one billing period in the future. However, the date for the first full invoice always falls within one billing period from the creation of the subscription or the ending of a free trial.

For example, assume that you create a two-month interval subscription in February and you cycle it at the end of every month by setting day_of_month to 31. The next month that has 31 days on two-month intervals from February is August, which results in a billing cycle anchor on August 31. However, the first full invoice date for this subscription still occurs in February. There’s an initial, prorated period from subscription creation until February 28 (or 29 during a leap year), followed by a full two-month billing period.

Use billing_cycle_anchor

You can create a subscription with an explicit billing cycle anchor using the Subscriptions API or Checkout.

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

Change the billing period on existing subscriptions

Use the Subscriptions API or Dashboard to change the billing date of an existing subscription through one of the following options:

• Reset the billing cycle anchor to the current time.
• Add a free trial to automatically set the anchor date to the end of the trial. Trials typically start when you create a subscription, but you can also apply them to existing subscriptions, allowing you to credit the customer for the days left in the previous cycle that they already paid.

Your billing cycle date changes in these scenarios. However, if you create or update a subscription with billing_mode[type]=flexible, the billing cycle anchor remains unchanged. Learn more about configuring flexible billing mode and its limitations.

• If all prices are zero-amount, adding one or more paid prices immediately resets the billing period. See the change subscription prices guide for more information.
• The billing_cycle_anchor resets to the cancel_at date when creating a subscription with cancel_at set to a date before the subscription renews next, or modifying an existing cancel_at date on a subscription with a billing_cycle_anchor in the future of the new cancel_at date.
• The billing_cycle_anchor resets to the current time when switching to a price with a different recurring.interval.

Reset the billing period to the current time

To reset the billing cycle anchor to the current time, make an update request with billing_cycle_anchor set to now. This sets the billing cycle anchor to the time of the update request. After you reset the billing cycle anchor, Stripe immediately sends an invoice. Enable proration to credit the customer for any days already paid in the previous period. Disabling proration might result in overcharging your customer.

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

Change the billing period using a trial period

You can change the billing cycle anchor by using a free trial to automatically set the billing cycle anchor date to the trial_end date.

For example, if a customer has an active subscription originally set to bill next on July 23, and on July 15 you introduce a trial period ending on August 1:

• The customer receives a 0 USD invoice on July 15. They already paid through July 23 in the previous cycle, so the “free” period only applies to July 24 through July 31.
• The customer isn’t billed on July 23.
• The new cycle billed on August 1 is a full cycle at the normal rate, then again on the 1st of each month after that.

Optionally, you can prevent prorations when you update a subscription to start a trial by using proration_behavior=none. In most cases, if you’re using the trial period to change the billing period without issuing a prorated invoice, you disable proration because the length of the trial period accounts for the portion already paid from the previous billing period.

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d trial_end=1627801200 \
  -d proration_behavior=none

Usage-based billing

With usage-based billing, the price paid by the customer varies based on consumption during the billing period. When changing the billing period results in ending a subscription’s service period early, you charge the customer for the usage accrued during the shortened billing period.

Thresholds

In addition to the regular cycle, you can configure subscriptions to bill whenever the amount due reaches a threshold.

If you have a subscription configured to invoice this way, you can set it up to reset the subscription service period when it hits the threshold.