Billing Anchors Explained: Preserving Renewal Dates in Subscription Recreation
Last updated:
When recreating subscriptions in a new Stripe account, one of the most common mistakes is failing to preserve the billing cycle anchor. This guide explains what billing anchors are, why they matter, and how to handle them correctly.
What Is a Billing Cycle Anchor?
A billing cycle anchor is the date on which a subscription’s billing cycle is based. It determines:
- When the customer is billed each period
- How proration is calculated when changes are made
- When the subscription renews
For example, if a customer subscribed on January 15th with a monthly plan, their billing anchor is the 15th of each month.
Why Billing Anchors Matter During Migration
When you create a new subscription without specifying the billing anchor, Stripe defaults to the creation date. This causes several problems:
Immediate Charges
If a customer was billed on the 15th and you recreate the subscription on the 20th without setting the anchor, they might be charged immediately for a new billing period.
Changed Renewal Dates
Customers expect their renewal date to stay consistent. A customer who signed up on the 15th might be confused when their statement shows a different date.
Proration Issues
Without the correct anchor, Stripe’s proration calculations won’t align with the customer’s expectations or your financial records.
How to Preserve Billing Anchors
When recreating a subscription in Stripe, you can explicitly set the billing cycle anchor using the billing_cycle_anchor parameter:
await stripe.subscriptions.create({
customer: 'cus_XYZ789',
items: [{ price: 'price_NEW123' }],
billing_cycle_anchor: originalSubscription.billing_cycle_anchor,
proration_behavior: 'none'
});Key Parameters
- billing_cycle_anchor: Unix timestamp of the original anchor date
- proration_behavior: Set to
'none'to avoid unexpected charges
What MoveMRR Does
MoveMRR automatically handles billing anchors during migration:
-
Reads the original anchor: For each subscription, MoveMRR captures the
billing_cycle_anchorfrom the source account. -
Applies it to the new subscription: When creating the subscription in the destination account, MoveMRR sets the same anchor.
-
Disables proration: To prevent any immediate charges, MoveMRR uses
proration_behavior: 'none'. -
Validates before execution: MoveMRR confirms that the anchor dates are within Stripe’s acceptable range.
Edge Cases and Considerations
Past Anchor Dates
Stripe allows setting a billing anchor in the past (within limits). This is useful when the customer’s next billing date has already passed relative to the migration date.
Annual Subscriptions
For annual subscriptions, the billing anchor is especially important. A customer expecting renewal on March 1st shouldn’t be billed in January because the migration happened to fall then.
Trial Periods
If a subscription was created with a trial, the billing anchor might differ from the subscription creation date. MoveMRR captures the correct anchor regardless of trial configuration.
Verifying Correct Anchor Dates
After migration, you can verify anchor dates in the Stripe Dashboard:
- Navigate to the subscription in the destination account
- Check the “Billing cycle anchor” field
- Compare it to the original subscription
The dates should match (accounting for timezone differences in display).