Billing Cycle Fresh

Control when subscriptions renew using billing cycle anchors.

How billing cycles work

A subscription's billing period depends on:

• The price interval (monthly, yearly, weekly, etc.)
• The billing cycle anchor — the reference timestamp that aligns all future billing dates

The anchor sets:

• Day of week for week intervals
• Day of month for month and year intervals
• Month of year for year intervals

Default anchor: subscription creation date (or trial end date if using a trial).

Examples

• Monthly subscription anchored to September 2 → bills on the 2nd of each month
• Monthly subscription anchored to January 31 → bills last day of each month (Feb 28, Mar 31, Apr 30...)
• Weekly subscription anchored to Friday → bills every Friday

Set billing cycle anchor on new subscriptions

Use billing_cycle_anchor_config (recommended for monthly/yearly)

Automatically handles short months and leap years:

# Renew on the 15th of each month
curl https://api.stripe.com/v1/subscriptions \
  -u "sk_test_YOUR_KEY:" \
  -d "customer=cus_123" \
  -d "items[0][price]=price_456" \
  -d "billing_cycle_anchor_config[day_of_month]=15"

# Renew on last day of month (set day_of_month=31)
curl https://api.stripe.com/v1/subscriptions \
  -u "sk_test_YOUR_KEY:" \
  -d "customer=cus_123" \
  -d "items[0][price]=price_456" \
  -d "billing_cycle_anchor_config[day_of_month]=31"

# Annual subscription renewing July 1
curl https://api.stripe.com/v1/subscriptions \
  -u "sk_test_YOUR_KEY:" \
  -d "customer=cus_123" \
  -d "items[0][price]=price_456" \
  -d "billing_cycle_anchor_config[month]=7" \
  -d "billing_cycle_anchor_config[day_of_month]=1"

All times use UTC. Anchor times default to subscription creation time if not specified.

Use billing_cycle_anchor directly

Pass a Unix timestamp:

curl https://api.stripe.com/v1/subscriptions \
  -u "sk_test_YOUR_KEY:" \
  -d "customer=cus_123" \
  -d "items[0][price]=price_456" \
  -d billing_cycle_anchor=1611008505

Use this for daily/weekly subscriptions or when you need an exact timestamp.

Proration when using a billing anchor

Stripe automatically creates a prorated invoice for the period between subscription creation and the first full billing date.

To skip the proration (make the initial period free):

curl https://api.stripe.com/v1/subscriptions \
  -u "sk_test_YOUR_KEY:" \
  -d "customer=cus_123" \
  -d "items[0][price]=price_456" \
  -d "billing_cycle_anchor_config[day_of_month]=1" \
  -d proration_behavior=none

Set anchor via Checkout

curl https://api.stripe.com/v1/checkout/sessions \
  -u "sk_test_YOUR_KEY:" \
  -d "line_items[][price]=price_456" \
  -d "line_items[][quantity]=1" \
  -d mode=subscription \
  -d success_url="https://example.com/success" \
  -d "subscription_data[billing_cycle_anchor]=1611008505"

Checkout must be in subscription mode. Note: Checkout doesn't support combining a trial with a billing cycle anchor.

Change billing cycle on existing subscriptions

Reset to now

curl https://api.stripe.com/v1/subscriptions/sub_123 \
  -u "sk_test_YOUR_KEY:" \
  -d billing_cycle_anchor=now \
  -d proration_behavior=create_prorations

This immediately generates an invoice. Always use create_prorations to avoid overcharging.

Use a trial period to change anchor

Set trial_end to the desired new anchor date. The trial end becomes the new billing cycle anchor.

curl https://api.stripe.com/v1/subscriptions/sub_123 \
  -u "sk_test_YOUR_KEY:" \
  -d trial_end=1627801200 \
  -d proration_behavior=none

Example: Customer billed on the 23rd. On the 15th, you set trial_end to the 1st of next month:

• Customer gets a $0 invoice on the 15th (already paid through the 23rd)
• Not billed on the 23rd
• Full billing resumes on the 1st of each month

Usage-based billing and cycle changes

When changing the billing period shortens a service period, usage accrued during the shortened period is billed at the end of that period.

Threshold billing

Subscriptions can also invoice when the amount due reaches a threshold, in addition to the regular cycle.