Setting the subscription billing cycle date

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.

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:

curl https://api.stripe.com/v1/subscriptions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="cus_4fdAW5ftNQow1a" \
  -d "items[0][price]"="price_CBb6IXqvTLXp3f" \
  -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 via 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 via the API

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

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 via the API

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

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.