— No Results

    Setting the subscription billing cycle date

    Subscriptions are billed on a cycle, learn how to set the billing 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 a trial period is used, to the trial end. It can also be explicitly set at the subscription’s creation.
    • The billing interval of its plan or plans.

    For example, a customer subscribed to a monthly plan set to cycle on the 2nd of the month will always be billed on the 2nd. A different customer, subscribed to that same plan starting on the 15th, will always be billed on the 15th.

    If a month does not 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][plan]"=plan_CBb6IXqvTLXp3f \
  -d billing_cycle_anchor=1577533159

    # Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

subscription = Stripe::Subscription.create({
    customer: 'cus_4fdAW5ftNQow1a',
    items: [{plan: 'plan_CBb6IXqvTLXp3f'}],
    billing_cycle_anchor: 1577533159,
})

    # Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

subscription = stripe.Subscription.create(
  customer='cus_4fdAW5ftNQow1a',
  items=[{'plan': 'plan_CBb6IXqvTLXp3f'}],
  billing_cycle_anchor=1577533159,
)

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

$subscription = \Stripe\Subscription::create([
    'customer' => 'cus_4fdAW5ftNQow1a',
    'items' => [['plan' => 'plan_CBb6IXqvTLXp3f']],
    'billing_cycle_anchor' => 1577533159,
]);

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Map<String, Object> item = new HashMap<>();
item.put("plan", "plan_CBb6IXqvTLXp3f");
Map<String, Object> items = new HashMap<>();
items.put("0", item);
Map<String, Object> params = new HashMap<>();
params.put("customer", "cus_4fdAW5ftNQow1a");
params.put("items", items);
params.put("billing_cycle_anchor", 1577533159);
Subscription subscription = Subscription.create(params);

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

(async () => {
  const subscription = await stripe.subscriptions.create({
    customer: 'cus_4fdAW5ftNQow1a',
    items: [{plan: 'plan_CBb6IXqvTLXp3f'}],
    billing_cycle_anchor: 1577533159,
  });
})();

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

items := []*stripe.SubscriptionItemsParams{
  {
    Plan: stripe.String("plan_CBb6IXqvTLXp3f"),
  },
}
params := &stripe.SubscriptionParams{
  Customer: stripe.String("cus_4fdAW5ftNQow1a"),
  Items: items,
  BillingCycleAnchor: stripe.Int64(1577533159),
}
subscription, _ := sub.New(params)

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var items = new List<SubscriptionItemOption> {
    new SubscriptionItemOption {Plan = "plan_CBb6IXqvTLXp3f"}
};
var options = new SubscriptionCreateOptions {
    Customer = "cus_4fdAW5ftNQow1a",
    Items = items,
    BillingCycleAnchor = DateTimeOffset.FromUnixTimeSeconds(1577533159).UtcDateTime,
};
var service = new SubscriptionService();
Subscription subscription = service.Create(options);

    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 prorate flag determines whether the customer receives a prorated invoice at all. If prorate is false, the initial period up to the billing cycle anchor will be free—similar to a free trial. Unlike a trial, there is no $0 invoice.

    Changing the billing cycle on pre-existing subscriptions

    There are two ways to change when an existing subscription is billed:

    1. Reset the anchor to the current time using billing_cycle_anchor=now. Be aware that this results in the customer being invoiced immediately. This can be done 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 plans and per-seat plans in advance: the customer paid for the current billing interval via the previous invoice.

    The prorate flag determines whether the customer receives a credit for the unused time from the previous invoice. When prorate is false, 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 do not 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 is not 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 is credited 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 prorate=true

    # Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::Subscription.update(
  'sub_49ty4767H20z6a',
  {
    billing_cycle_anchor: 'now',
    prorate: true,
  }
)

    # Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.Subscription.modify('sub_49ty4767H20z6a',
  billing_cycle_anchor='now',
  prorate=True,
)

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\Subscription::update('sub_49ty4767H20z6a', [
    'billing_cycle_anchor' => 'now',
    'prorate' => true,
]);

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Subscription subscription = Subscription.retrieve("sub_49ty4767H20z6a");
Map<String, Object> params = new HashMap<>();
params.put("billing_cycle_anchor", "now");
params.put("prorate", true);
subscription.update(params);

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

(async () => {
  const subscription = await stripe.subscriptions.update('sub_49ty4767H20z6a', {
    billing_cycle_anchor: 'now',
    prorate: true,
  });
})();

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.SubscriptionParams{
  BillingCycleAnchorNow: stripe.Bool(true),
  Prorate: stripe.Bool(true),
}
subscription, _ := sub.Update("sub_49ty4767H20z6a", params)

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new SubscriptionUpdateOptions {
    BillingCycleAnchor = SubscriptionBillingCycleAnchor.Now,
    Prorate = true,
};
var service = new SubscriptionService();
Subscription subscription = service.Update("sub_49ty4767H20z6a", options);

    With this approach, you probably want the default behavior of setting prorate to true—as in the code sample—so the customer is not 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 is May 15 and a customer has an active subscription set to bill next on May 23, and you introduce a trial period until June 1st:

    • The customer will not be billed on May 23.
    • The customer will be billed next on June 1, then on July 1, and so on.

    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=1577533159 \
  -d prorate=false

    # Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::Subscription.update(
  'sub_49ty4767H20z6a',
  {
    trial_end: 1577533159,
    prorate: false,
  }
)

    # Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.Subscription.modify('sub_49ty4767H20z6a',
  trial_end=1577533159,
  prorate=False,
)

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\Subscription::update('sub_49ty4767H20z6a', [
    'trial_end' => 1577533159,
    'prorate' => false,
]);

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Subscription subscription = Subscription.retrieve("sub_49ty4767H20z6a");
Map<String, Object> params = new HashMap<>();
params.put("trial_end", 1577533159);
params.put("prorate", false);
subscription.update(params);

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

(async () => {
  const subscription = await stripe.subscriptions.update('sub_49ty4767H20z6a', {
    trial_end: 1577533159,
    prorate: false,
  });
})();

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.SubscriptionParams{
  TrialEnd: stripe.Int64(1577533159),
  Prorate: stripe.Bool(false),
}
subscription, _ := sub.Update("sub_49ty4767H20z6a", params)

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new SubscriptionUpdateOptions {
    TrialEnd = DateTimeOffset.FromUnixTimeSeconds(1577533159).UtcDateTime,
    Prorate = false,
};
var service = new SubscriptionService();
Subscription subscription = service.Update("sub_49ty4767H20z6a", options);

    As a reminder, you probably want to also set prorate to false—as in the above code—so the customer is not credited for previously paid, but unused time.

    Thresholds

    In addition to the regular cycle, subscriptions may be configured to bill whenever the amount due reaches a threshold. If 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 via the Dashboard

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

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

    We do not currently support resetting billing_cycle_anchor via the Dashboard.

    Metered billing

    In a metered billing plan, 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, metered billing plans simply charge for the usage accrued during the shortened billing period.

    Next steps

    Congrats! You know how to change a subscription’s billing cycle. Some resources you might want to see next:

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team.

    You can chat live with other developers in #stripe on freenode or subscribe to our YouTube channel.

    On this page