# Setting the subscription billing cycle date Learn how to set the billing date for subscriptions. A subscription’s billing cycle depends on two factors: * The recurring interval of its [price](https://docs.stripe.com/products-prices/overview.md) or prices, such as monthly, yearly, weekly, and so on. * The [billing cycle anchor](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-billing_cycle_anchor) is the reference point that aligns future billing cycle 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. Billing cycle anchors are UNIX timestamps in seconds from the current epoch. The following are examples of monthly subscriptions with different billing cycles: - 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 The subscription creation time matches the time of the request. It is not the same as the subscription start date. Learn more about [backdating and billing cycle anchors](https://docs.stripe.com/billing/subscriptions/backdating.md#backdating-billing-cycle). 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 cycle 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](https://docs.stripe.com/api.md#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 cycles at the end of the month, even in months with less than 31 days. If a month has less than 31 days, the subscription cycles on the last day of that month. ```dotnet StripeConfiguration.ApiKey = "<>"; var options = new SubscriptionCreateOptions { Customer = "<>", Items = new List { new SubscriptionItemOptions { Price = "<>" }, }, BillingCycleAnchorConfig = new SubscriptionBillingCycleAnchorConfigOptions { DayOfMonth = 31 }, }; var service = new SubscriptionService(); Subscription subscription = service.Create(options); ``` ```go stripe.Key = "<>" params := &stripe.SubscriptionParams{ Customer: stripe.String("<>"), Items: []*stripe.SubscriptionItemsParams{ &stripe.SubscriptionItemsParams{Price: stripe.String("<>")}, }, BillingCycleAnchorConfig: &stripe.SubscriptionBillingCycleAnchorConfigParams{ DayOfMonth: stripe.Int64(31), }, }; result, err := subscription.New(params); ``` ```java Stripe.apiKey = "<>"; SubscriptionCreateParams params = SubscriptionCreateParams.builder() .setCustomer("<>") .addItem(SubscriptionCreateParams.Item.builder().setPrice("<>").build()) .setBillingCycleAnchorConfig( SubscriptionCreateParams.BillingCycleAnchorConfig.builder().setDayOfMonth(31L).build() ) .build(); Subscription subscription = Subscription.create(params); ``` ```node const stripe = require('stripe')('<>'); const subscription = await stripe.subscriptions.create({ customer: '<>', items: [ { price: '<>', }, ], billing_cycle_anchor_config: { day_of_month: 31, }, }); ``` ```python import stripe stripe.api_key = "<>" subscription = stripe.Subscription.create( customer="<>", items=[{"price": "<>"}], billing_cycle_anchor_config={"day_of_month": 31}, ) ``` ```php $stripe = new \Stripe\StripeClient('<>'); $subscription = $stripe->subscriptions->create([ 'customer' => '<>', 'items' => [['price' => '<>']], 'billing_cycle_anchor_config' => ['day_of_month' => 31], ]); ``` ```ruby Stripe.api_key = '<>' subscription = Stripe::Subscription.create({ customer: '<>', items: [{price: '<>'}], 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`. ```dotnet StripeConfiguration.ApiKey = "<>"; var options = new SubscriptionCreateOptions { Customer = "<>", Items = new List { new SubscriptionItemOptions { Price = "<>" }, }, BillingCycleAnchorConfig = new SubscriptionBillingCycleAnchorConfigOptions { Month = 7, DayOfMonth = 1, }, }; var service = new SubscriptionService(); Subscription subscription = service.Create(options); ``` ```go stripe.Key = "<>" params := &stripe.SubscriptionParams{ Customer: stripe.String("<>"), Items: []*stripe.SubscriptionItemsParams{ &stripe.SubscriptionItemsParams{Price: stripe.String("<>")}, }, BillingCycleAnchorConfig: &stripe.SubscriptionBillingCycleAnchorConfigParams{ Month: stripe.Int64(7), DayOfMonth: stripe.Int64(1), }, }; result, err := subscription.New(params); ``` ```java Stripe.apiKey = "<>"; SubscriptionCreateParams params = SubscriptionCreateParams.builder() .setCustomer("<>") .addItem(SubscriptionCreateParams.Item.builder().setPrice("<>").build()) .setBillingCycleAnchorConfig( SubscriptionCreateParams.BillingCycleAnchorConfig.builder() .setMonth(7L) .setDayOfMonth(1L) .build() ) .build(); Subscription subscription = Subscription.create(params); ``` ```node const stripe = require('stripe')('<>'); const subscription = await stripe.subscriptions.create({ customer: '<>', items: [ { price: '<>', }, ], billing_cycle_anchor_config: { month: 7, day_of_month: 1, }, }); ``` ```python import stripe stripe.api_key = "<>" subscription = stripe.Subscription.create( customer="<>", items=[{"price": "<>"}], billing_cycle_anchor_config={"month": 7, "day_of_month": 1}, ) ``` ```php $stripe = new \Stripe\StripeClient('<>'); $subscription = $stripe->subscriptions->create([ 'customer' => '<>', 'items' => [['price' => '<>']], 'billing_cycle_anchor_config' => [ 'month' => 7, 'day_of_month' => 1, ], ]); ``` ```ruby Stripe.api_key = '<>' subscription = Stripe::Subscription.create({ customer: '<>', items: [{price: '<>'}], billing_cycle_anchor_config: { month: 7, 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` does not 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. ```dotnet StripeConfiguration.ApiKey = "<>"; var options = new SubscriptionCreateOptions { Customer = "<>", Items = new List { new SubscriptionItemOptions { Price = "<>" }, }, BillingCycleAnchorConfig = new SubscriptionBillingCycleAnchorConfigOptions { DayOfMonth = 15, Hour = 12, Minute = 30, Second = 0, }, }; var service = new SubscriptionService(); Subscription subscription = service.Create(options); ``` ```go stripe.Key = "<>" params := &stripe.SubscriptionParams{ Customer: stripe.String("<>"), Items: []*stripe.SubscriptionItemsParams{ &stripe.SubscriptionItemsParams{Price: stripe.String("<>")}, }, BillingCycleAnchorConfig: &stripe.SubscriptionBillingCycleAnchorConfigParams{ DayOfMonth: stripe.Int64(15), Hour: stripe.Int64(12), Minute: stripe.Int64(30), Second: stripe.Int64(0), }, }; result, err := subscription.New(params); ``` ```java Stripe.apiKey = "<>"; SubscriptionCreateParams params = SubscriptionCreateParams.builder() .setCustomer("<>") .addItem(SubscriptionCreateParams.Item.builder().setPrice("<>").build()) .setBillingCycleAnchorConfig( SubscriptionCreateParams.BillingCycleAnchorConfig.builder() .setDayOfMonth(15L) .setHour(12L) .setMinute(30L) .setSecond(0L) .build() ) .build(); Subscription subscription = Subscription.create(params); ``` ```node const stripe = require('stripe')('<>'); const subscription = await stripe.subscriptions.create({ customer: '<>', items: [ { price: '<>', }, ], billing_cycle_anchor_config: { day_of_month: 15, hour: 12, minute: 30, second: 0, }, }); ``` ```python import stripe stripe.api_key = "<>" subscription = stripe.Subscription.create( customer="<>", items=[{"price": "<>"}], billing_cycle_anchor_config={"day_of_month": 15, "hour": 12, "minute": 30, "second": 0}, ) ``` ```php $stripe = new \Stripe\StripeClient('<>'); $subscription = $stripe->subscriptions->create([ 'customer' => '<>', 'items' => [['price' => '<>']], 'billing_cycle_anchor_config' => [ 'day_of_month' => 15, 'hour' => 12, 'minute' => 30, 'second' => 0, ], ]); ``` ```ruby Stripe.api_key = '<>' subscription = Stripe::Subscription.create({ customer: '<>', items: [{price: '<>'}], billing_cycle_anchor_config: { day_of_month: 15, hour: 12, minute: 30, 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. Call [create subscription](https://docs.stripe.com/api.md#create_subscription), setting a timestamp for `billing_cycle_anchor`. ```dotnet StripeConfiguration.ApiKey = "<>"; var options = new SubscriptionCreateOptions { Customer = "<>", Items = new List { new SubscriptionItemOptions { Price = "<>" }, }, BillingCycleAnchor = DateTimeOffset.FromUnixTimeSeconds(1611008505).UtcDateTime, }; var service = new SubscriptionService(); Subscription subscription = service.Create(options); ``` ```go stripe.Key = "<>" params := &stripe.SubscriptionParams{ Customer: stripe.String("<>"), Items: []*stripe.SubscriptionItemsParams{ &stripe.SubscriptionItemsParams{Price: stripe.String("<>")}, }, BillingCycleAnchor: stripe.Int64(1611008505), }; result, err := subscription.New(params); ``` ```java Stripe.apiKey = "<>"; SubscriptionCreateParams params = SubscriptionCreateParams.builder() .setCustomer("<>") .addItem(SubscriptionCreateParams.Item.builder().setPrice("<>").build()) .setBillingCycleAnchor(1611008505L) .build(); Subscription subscription = Subscription.create(params); ``` ```node const stripe = require('stripe')('<>'); const subscription = await stripe.subscriptions.create({ customer: '<>', items: [ { price: '<>', }, ], billing_cycle_anchor: 1611008505, }); ``` ```python import stripe stripe.api_key = "<>" subscription = stripe.Subscription.create( customer="<>", items=[{"price": "<>"}], billing_cycle_anchor=1611008505, ) ``` ```php $stripe = new \Stripe\StripeClient('<>'); $subscription = $stripe->subscriptions->create([ 'customer' => '<>', 'items' => [['price' => '<>']], 'billing_cycle_anchor' => 1611008505, ]); ``` ```ruby Stripe.api_key = '<>' subscription = Stripe::Subscription.create({ customer: '<>', items: [{price: '<>'}], billing_cycle_anchor: 1611008505, }) ``` ### Configure proration behavior Regardless of which API parameter you use, Stripe automatically creates a prorated invoice to bill for the period between the subscription creation date and the first full invoice date. If you don’t want to immediately charge a customer for the period between the subscription creation and the first full invoice date, either: - [Disable the proration](https://docs.stripe.com/billing/subscriptions/prorations.md#disable-prorations) by setting `proration_behavior` to `none`, making the initial period up to the first full invoice date free. This action doesn’t generate an invoice at all until the first billing cycle. - [Combine a trial with the billing_cycle_anchor](https://docs.stripe.com/billing/subscriptions/trials.md#combine-trial-anchor) by setting `trial_end` to a timestamp representing the date when the free trial ends. Depending on the duration of the free trial and the number of days until the first full invoice date, this option might result in a prorated invoice following the trial period. For example, a free trial is 7 days and the billing cycle is monthly on the 1st. If the customer subscribes on the 15th, we generate a prorated invoice on the 22nd for the period between the 22nd and the 1st, then invoice for the full amount on the 1st of each month thereafter. If a customer subscribes on the 28th, the free trial extends past the 1st, generating a prorated invoice until the next month. Call the Stripe Checkout [create session](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session) with a timestamp for `subscription_data.billing_cycle_anchor`: ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[][price]"="<>" \ -d "line_items[][quantity]"=1 \ -d "mode"="subscription" \ ``` ```ruby <> session = Stripe::Checkout::Session.create( line_items: [{ price: '<>', quantity: 1, }], mode: 'subscription', ) # Record the session ID in your system session_id = session.id # 303 redirect to session.url ``` ```python <> session = stripe.checkout.Session.create( line_items=[{ 'price': '<>', 'quantity': 1, }], mode='subscription', ) # Record the session ID in your system session_id = session.id # 303 redirect to session.url ``` ```php <> $session = \Stripe\Checkout\Session::create([ 'line_items' => [[ 'price' => '<>', 'quantity' => 1, ]], 'mode' => 'subscription', ]); // Record the session ID in your system $session_id = $session->id // 303 redirect to $session->url ``` ```java <> SessionCreateParams params = SessionCreateParams.builder() .addLineItem( SessionCreateParams.LineItem.builder() .setQuantity(1L) .setPrice("<>") .build()) .setMode(SessionCreateParams.Mode.SUBSCRIPTION) .build(); Session session = Session.create(params); // Record the session ID in your system String sessionId = session.getId(); // 303 redirect to session.getUrl() ``` ```javascript <> const session = await stripe.checkout.sessions.create({ line_items: [{ price: '<>', quantity: 1, }], mode: 'subscription', }); // Record the session ID in your system const session_id = session.id // 303 redirect to session.url ``` ```go <> params := &stripe.CheckoutSessionParams{ LineItems: []*stripe.CheckoutSessionLineItemParams{ &stripe.CheckoutSessionLineItemParams{ Price: stripe.String("<>"), Quantity: stripe.Int64(1), }, }, Mode: stripe.String("subscription"), } session, err := session.New(params) // Record the session ID in your system session_id := session.ID // 303 redirect to session.URL ``` ```dotnet <> var options = new SessionCreateOptions { LineItems = new List { new SessionLineItemOptions { Price = "<>", Quantity = 1, }, }, Mode = "subscription", }; var service = new SessionService(); Session session = service.Create(options); // Record the session ID in your system string sessionId = session.getId() // 303 redirect to session.Url ``` Checkout must be in `subscription` mode to configure a billing cycle anchor. ### Configure proration behavior You can configure how to handle the period between subscription creation and the first full invoice date using the `proration_behavior` parameter. Checkout doesn’t support combining a trial with the billing cycle anchor. - Keep the default `create_prorations` setting to allow Stripe to immediately invoice the customer for the period between the subscription date and the first full invoice date. - [Disable the proration](https://docs.stripe.com/payments/checkout/billing-cycle.md?ui=embedded-form#disable-prorations) by setting `proration_behavior` to `none`, making the initial period free (up to the first full invoice date). This action doesn’t generate an invoice at all until the first billing cycle. You can’t use one-time prices in Checkout Sessions when `proration_behavior` is `none`. ## Change the billing cycle on pre-existing subscriptions Use the [Subscriptions API](https://docs.stripe.com/api/subscriptions/update.md) or [Dashboard](https://dashboard.stripe.com/subscriptions) 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](https://docs.stripe.com/billing/subscriptions/trials.md) 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. - If all the prices are zero-amount, adding one or more paid prices immediately resets the billing period. See the [change subscription prices guide](https://docs.stripe.com/billing/subscriptions/change-price.md#handling-zero-amount-prices-and-quantities) for more details on this scenario. ### Reset the billing cycle to the current time To reset the billing cycle anchor, make an update request with `billing_cycle_anchor` set to `now`. This sets the billing cycle anchor to the time of the update request. When you reset the billing cycle anchor, Stripe immediately sends an invoice. [Enable proration](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-proration_behavior) to credit the customer for any days already paid in the previous period. Disabling proration might result in overcharging your customer. Call [update the subscription](https://docs.stripe.com/api.md#update_subscription), setting `billing_cycle_anchor` to `now` and `proration_behavior` to `create_prorations` to prevent overcharging the customer for any days they already paid in the previous cycle. 1. From the [Subscriptions overview](https://docs.stripe.com/api/subscriptions.md), click the overflow menu ⋯ and choose **Update subscription**. 1. Scroll to **Advanced options** and select **Reset the billing cycle**. 1. Select the **Prorate changes** toggle to prevent overcharging for the days already paid from the previous cycle. 1. Click **Update subscription**. ### Add a trial to change the billing cycle Adding a non-prorated trial period to an existing subscription allows you to configure the billing cycle to be any date. Typically, if you’re using the trial period to change the billing cycle 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 cycle. For example, if a customer has an active subscription set to bill next on July 23, and you introduce a trial period until August 1: * The customer receives a 0 USD invoice on July 15. * The customer isn’t billed on July 23. * The customer is billed next on August 1, then on September 1, and so on. * The customer already paid through July 23 in the previous cycle, so that “free” period isn’t actually free. * The period between July 23 and July 31 isn’t charged. * The new cycle billed on August 1 is a full cycle at the normal rate. Call [update subscription](https://docs.stripe.com/api.md#update_subscription), setting `trial_end` to a Unix timestamp representing the end date for the trial (also the new billing cycle anchor) and `proration_behavior` to `none`. ```dotnet StripeConfiguration.ApiKey = "<>"; var options = new SubscriptionUpdateOptions { TrialEnd = DateTimeOffset.FromUnixTimeSeconds(1611008505).UtcDateTime, ProrationBehavior = "none", }; var service = new SubscriptionService(); Subscription subscription = service.Update("sub_49ty4767H20z6a", options); ``` ```go stripe.Key = "<>" params := &stripe.SubscriptionParams{ TrialEnd: stripe.Int64(1611008505), ProrationBehavior: stripe.String("none"), }; result, err := subscription.Update("sub_49ty4767H20z6a", params); ``` ```java Stripe.apiKey = "<>"; Subscription resource = Subscription.retrieve("sub_49ty4767H20z6a"); SubscriptionUpdateParams params = SubscriptionUpdateParams.builder() .setTrialEnd(1611008505L) .setProrationBehavior(SubscriptionUpdateParams.ProrationBehavior.NONE) .build(); Subscription subscription = resource.update(params); ``` ```node const stripe = require('stripe')('<>'); const subscription = await stripe.subscriptions.update( 'sub_49ty4767H20z6a', { trial_end: 1611008505, proration_behavior: 'none', } ); ``` ```python import stripe stripe.api_key = "<>" subscription = stripe.Subscription.modify( "sub_49ty4767H20z6a", trial_end=1611008505, proration_behavior="none", ) ``` ```php $stripe = new \Stripe\StripeClient('<>'); $subscription = $stripe->subscriptions->update( 'sub_49ty4767H20z6a', [ 'trial_end' => 1611008505, 'proration_behavior' => 'none', ] ); ``` ```ruby Stripe.api_key = '<>' subscription = Stripe::Subscription.update( 'sub_49ty4767H20z6a', { trial_end: 1611008505, proration_behavior: 'none', }, ) ``` 1. From the [Subscriptions overview](https://docs.stripe.com/api/subscriptions.md), select the subscription you want to change to open its Details page. 1. Click **Actions** > **Update subscription**. 1. Click **Add trial** and enter the number of days of the trial. The end of the trial becomes the new billing cycle anchor date. 1. Deselect the **Prorate changes** toggle to prevent crediting the customer for already paid days. 1. Click **Update subscription**. ## Metered billing With [metered billing](https://docs.stripe.com/products-prices/pricing-models.md), 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](https://docs.stripe.com/billing/subscriptions/trials.md) * [Update Subscription](https://docs.stripe.com/api.md#update_subscription)