Set the billing cycle date

When you create a Checkout Session, you can explicitly set a subscription’s billing cycle anchor to a fixed date, such as the 1st of the next month. The billing cycle anchor determines the first date when customers are billed the full subscription amount. The billing cycle anchor and the recurring interval of its price determine a subscription’s future billing dates. For example, a monthly subscription created on May 15 with an anchor at June 1 is billed on May 15, then on the 1st of the month for the life of the subscription.

There are two ways to set the billing cycle anchor:

• Use subscription_data.billing_cycle_anchor_config to describe a recurring billing date with explicit fields for day_of_month, month, hour, minute, and second (monthly and yearly subscriptions only). Stripe automatically accounts for short months and leap years.
• Use subscription_data.billing_cycle_anchor to set the anchor directly as a future UNIX timestamp.

Use the proration_behavior parameter to customize how to handle prorations for the initial billing period up until the first full invoice date. By default, proration_behavior is set to create_prorations, and customers receive a prorated invoice. If proration_behavior is none, the first invoice is waived, meaning that they are subscribed for free during the first period and they only get an invoice after the billing cycle anchor, which would then include the full amount.

Set the billing cycle date with a config object

For monthly and yearly subscriptions, use subscription_data.billing_cycle_anchor_config to specify the billing renewal date with a config object instead of a raw timestamp. Stripe automatically handles edge cases like short months and leap years.

For example, to anchor billing to the 1st of every month, set day_of_month to 1. To anchor a yearly subscription to July 1, set month to 7 and day_of_month to 1.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "line_items[0][price]=
{{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=subscription \
  --data-urlencode "success_url=https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \
  -d "subscription_data[billing_cycle_anchor_config][day_of_month]=1"

You can also specify hour, minute, and second for precise control over the anchor time. If omitted, they default to the time of the subscription creation request (in UTC).

billing_cycle_anchor_config is only compatible with monthly and yearly subscriptions. For daily or weekly subscriptions, use billing_cycle_anchor with a UNIX timestamp instead.

Create a Checkout Session with a billing cycle anchor

To configure a billing cycle anchor with a UNIX timestamp, set the subscription_data.billing_cycle_anchor parameter when you create a Checkout Session in subscription mode. The anchor must be a future UNIX timestamp within the first billing period (the current timestamp plus the recurring interval duration).

curl https://api.stripe.com/v1/checkout/sessions \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "line_items[0][price]=
{{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=subscription \
  --data-urlencode "success_url=https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \
  -d "subscription_data[billing_cycle_anchor]=1611008505"

If a customer attempts payment after a session’s active period has passed the date set for the billing cycle anchor, Checkout charges for the full period starting with the billing cycle anchor instead of the prorated period before the billing cycle anchor.

Disable prorations

To disable prorations, set the subscription_data.proration_behavior parameter to none when creating a Checkout Session.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "line_items[0][price]=
{{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=subscription \
  --data-urlencode "success_url=https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \
  -d "subscription_data[billing_cycle_anchor]=1611008505" \
  -d "subscription_data[proration_behavior]=none"

Similar to a free trial, the customer isn’t charged for the initial period up to the billing cycle anchor. Unlike a trial, no 0 USD invoice is generated. Customers receive an invoice with the full subscription amount on the billing cycle anchor date.

In the Checkout Session response object, amounts attached to the line items and total details are always 0 when prorations are disabled. Additionally, the payment status of the Session is set to no_payment_required to reflect that payment is delayed to a future date.

Limitations

• You can’t use trials in Checkout Sessions with a billing cycle anchor.
• You can’t use one-time prices in Checkout Sessions when proration_behavior is none.
• You can’t apply amount_off coupons to Checkout Sessions with a default proration_behavior of create_prorations.