— 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 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 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][price]"=price_CBb6IXqvTLXp3f \
  -d billing_cycle_anchor=1592458995

    # Set your secret key. Remember to switch 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: [
      {
        price: 'price_CBb6IXqvTLXp3f',
      },
    ],
    billing_cycle_anchor: 1592458995,
})

    # Set your secret key. Remember to switch 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=[
    {
      'price': 'price_CBb6IXqvTLXp3f',
    },
  ],
  billing_cycle_anchor=1592458995,
)

    // Set your secret key. Remember to switch 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' => [
      [
        'price' => 'price_CBb6IXqvTLXp3f',
      ],
    ],
    'billing_cycle_anchor' => 1592458995,
]);

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

SubscriptionCreateParams params =
  SubscriptionCreateParams.builder()
    .setCustomer("cus_4fdAW5ftNQow1a")
    .addItem(
      SubscriptionCreateParams.Item.builder()
        .setPrice("price_CBb6IXqvTLXp3f")
        .build())
    .setBillingCycleAnchor(1592458995L)
    .build();

Subscription subscription = Subscription.create(params);

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

const subscription = await stripe.subscriptions.create({
  customer: 'cus_4fdAW5ftNQow1a',
  items: [
    {
      price: 'price_CBb6IXqvTLXp3f',
    },
  ],
  billing_cycle_anchor: 1592458995,
});

    // Set your secret key. Remember to switch 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{
  {
    Price: stripe.String("price_CBb6IXqvTLXp3f"),
  },
}
params := &stripe.SubscriptionParams{
  Customer: stripe.String("cus_4fdAW5ftNQow1a"),
  Items: items,
  BillingCycleAnchor: stripe.Int64(1592458995),
}
subscription, _ := sub.New(params)

    // Set your secret key. Remember to switch 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<SubscriptionItemOptions> {
    new SubscriptionItemOptions {Price = "price_CBb6IXqvTLXp3f"}
};
var options = new SubscriptionCreateOptions {
    Customer = "cus_4fdAW5ftNQow1a",
    Items = items,
    BillingCycleAnchor = DateTimeOffset.FromUnixTimeSeconds(1592458995).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 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 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 prices and per-seat prices in advance: the customer paid for the current recurring interval via 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 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 proration_behavior=create_prorations

    # Set your secret key. Remember to switch 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',
    proration_behavior: 'create_prorations',
  }
)

    # Set your secret key. Remember to switch 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',
  proration_behavior='create_prorations',
)

    // Set your secret key. Remember to switch 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',
    'proration_behavior' => 'create_prorations',
]);

    // Set your secret key. Remember to switch 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");

SubscriptionUpdateParams params =
  SubscriptionUpdateParams.builder()
    .setBillingCycleAnchor(SubscriptionUpdateParams.BillingCycleAnchor.NOW)
    .setProrationBehavior(SubscriptionUpdateParams.ProrationBehavior.CREATE_PRORATIONS)
    .build();

subscription.update(params);

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

const subscription = await stripe.subscriptions.update('sub_49ty4767H20z6a', {
  billing_cycle_anchor: 'now',
  proration_behavior: 'create_prorations',
});

    // Set your secret key. Remember to switch 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),
  ProrationBehavior:     stripe.String(string(stripe.SubscriptionProrationBehaviorCreateProrations)),
}
subscription, _ := sub.Update("sub_49ty4767H20z6a", params)

    // Set your secret key. Remember to switch 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,
    ProrationBehavior = "create_prorations",
};
var service = new SubscriptionService();
Subscription subscription = service.Update("sub_49ty4767H20z6a", options);

    With this approach, you probably want the default behavior of setting proration_behavior to create_prorations—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=1592458995 \
  -d proration_behavior=none

    # Set your secret key. Remember to switch 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: 1592458995,
    proration_behavior: 'none',
  }
)

    # Set your secret key. Remember to switch 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=1592458995,
  proration_behavior='none',
)

    // Set your secret key. Remember to switch 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' => 1592458995,
    'proration_behavior' => 'none',
]);

    // Set your secret key. Remember to switch 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");

SubscriptionUpdateParams params =
  SubscriptionUpdateParams.builder()
    .setTrialEnd(1592458995L)
    .setProrationBehavior(SubscriptionUpdateParams.ProrationBehavior.NONE)
    .build();

subscription.update(params);

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

const subscription = await stripe.subscriptions.update('sub_49ty4767H20z6a', {
  trial_end: 1592458995,
  proration_behavior: 'none',
});

    // Set your secret key. Remember to switch 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(1592458995),
  ProrationBehavior: stripe.String(string(stripe.SubscriptionProrationBehaviorNone)),
}
subscription, _ := sub.Update("sub_49ty4767H20z6a", params)

    // Set your secret key. Remember to switch 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(1592458995).UtcDateTime,
    ProrationBehavior = "none",
};
var service = new SubscriptionService();
Subscription subscription = service.Update("sub_49ty4767H20z6a", options);

    As a reminder, you probably want to also set proration_behavior to none—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

    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, the customer is charged 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?
    Feedback about this page?

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

    Questions? Contact us.

    Developer tutorials on YouTube.

    On this page