Stripe billing_cycle_anchor & _config Explained (2026)

Direct answer: The purpose of billing_cycle_anchor in Stripe subscriptions is to define the reference date that all future billing cycles align to: it determines when each recurring invoice is issued and how prorations are calculated. By default the anchor is the subscription’s creation time; set it explicitly to bill on a different date, or use billing_cycle_anchor_config to pin billing to a fixed calendar day such as the 1st of the month. The anchor does not control the first charge on its own — start_date, trial_end, collection_method, and proration_behavior all interact with it. That interaction matters most when recreating subscriptions in another Stripe account: a migration must preserve the customer’s next expected charge date and paid service period, not just copy a timestamp from the source subscription. Get it wrong and the customer is billed by two accounts, or the renewal silently shifts to the migration date.

Stripe’s Billing migration toolkit includes fields for both start_date and billing_cycle_anchor, which is a useful reminder that creation timing and recurring cadence are separate decisions.

What Is the Purpose of billing_cycle_anchor in Stripe?

The billing-cycle anchor influences:

• the recurring renewal cadence;
• when a full recurring invoice is expected;
• how prorations are calculated when subscription configuration changes.

It does not independently prove:

• that the customer has a valid default payment method;
• that the first destination invoice will not require authentication;
• that no trial or scheduled phase changes the first charge;
• that the source account has stopped collecting.

What Is billing_cycle_anchor_config and How Is It Different?

billing_cycle_anchor_config is the calendar-based way to set the anchor. Instead of passing one absolute timestamp, you pass a recurring rule — day_of_month, and optionally month, hour, minute, second — and Stripe derives the next matching anchor date itself. Use it when every subscription should bill on the same calendar day (for example, always on the 1st), rather than on the anniversary of its creation.

Differences that matter in practice:

• billing_cycle_anchor takes a Unix timestamp; billing_cycle_anchor_config takes a calendar rule. They are alternative ways to control the same anchor — do not send both on the same request.
• billing_cycle_anchor_config can only be set when the subscription is created; changing the cycle later means updating the anchor through a subscription update with the appropriate proration setting.
• With either variant, the period between start and the first full cycle is handled by proration_behavior — a calendar rule does not by itself decide whether that partial period is charged, credited, or skipped.
• For months without the configured day (for example, the 31st), Stripe bills on the last day of the shorter month.

In a migration, a source subscription created with billing_cycle_anchor_config still exposes its concrete next renewal via current_period_end. Recreating it in the destination account with a timestamp anchor on that date preserves the customer’s schedule; re-applying the calendar rule is only necessary if the destination should keep the fixed-day behaviour for future plan changes. Primary source: Stripe billing cycle documentation.

Which Fields Must Be Reconciled Together During a Migration?

Field or state	Migration question
start_date	When should the destination subscription or schedule begin?
billing_cycle_anchor	Which recurring date should future cycles align to?
trial_end	Is the remaining trial being preserved, ended, or restarted?
proration_behavior	Should creation or a schedule change produce a proration?
collection_method	Will Stripe charge a saved method or send an invoice?
cancel_at_period_end	Was the source subscription already set to end?
Source current-period boundary	Which account owns the final paid source period?
Destination default payment method	Can automatic collection occur on the planned date?

The correct configuration is the one that matches the commercial agreement and expected next invoice.

A Concrete Example

Assume:

• the source subscription renews monthly on 15 August;
• the customer has paid through 14 August;
• the migration project runs on 5 August.

A controlled plan usually schedules the destination to take over at the next agreed boundary and prevents the source from also renewing on 15 August. Creating an immediately billable destination subscription on 5 August would shorten the paid period or create an overlapping charge.

If the source renews during the cutover window, decide which account takes that renewal first. Do not “fix” it afterward by changing only the anchor.

How Do You Preserve Renewal Dates When Recreating a Subscription?

Three patterns cover most Stripe-to-Stripe recreations. All three aim at the same outcome — the destination’s first full invoice lands on the date the customer already expects — but they behave differently around the start:

1. Future anchor with no proration. Create the destination subscription now, set billing_cycle_anchor to the source’s current_period_end, and send proration_behavior: "none". The subscription is active immediately and the first full invoice is issued at the anchor. This is the pattern Stripe’s own Stripe-to-Stripe toolkit example follows.
2. Trial until renewal. Create the subscription with trial_end set to the source’s current_period_end. No charge occurs during the trial, and the billing cycle anchors to the trial’s end. Functionally similar to the first pattern, but the subscription reports trialing until cutover — relevant if your product logic or dunning treats trials differently.
3. Backdated start. Pass a historical start_date/backdate_start_date so the destination records when the relationship really began, combined with a future anchor for the next charge. Useful when invoice history context matters in the destination account; it does not by itself prevent an immediate charge — the anchor and proration settings still decide that.

Whichever pattern is used, verify the destination’s current_period_end equals the customer’s expected renewal date after creation, and confirm the source is deactivated before that date arrives.

Stripe Billing Migration Toolkit Rules

Stripe currently documents:

• a production start_date at least 24 hours in the future;
• a one-hour minimum in a sandbox;
• a 24-hour scheduled state before production subscriptions go live;
• billing_cycle_anchor, trial_end, and proration_behavior fields in the CSV specification;
• a Stripe-to-Stripe example that uses the source current-period end as the destination start and a future billing date as the anchor.

Primary source: Stripe Billing migration toolkit.

These are toolkit rules, not a universal API recipe. If an internal script or MoveMRR workflow is used, inspect the plan generated for each subscription type.

Edge Cases

Annual and Prepaid Subscriptions

An annual customer may have many months of service remaining. The purchase agreement should say whether the seller retains the prepaid revenue, whether the buyer receives an adjustment, and when the destination first bills. This is an accounting decision as well as a Stripe configuration.

Active Trials

Preserve the intended trial end when that is part of the customer agreement. An anchor alone does not preserve a trial.

Multiple Subscription Items

All recurring items must have a compatible destination schedule. Check quantities, intervals, currencies, and any mixed-interval behaviour rather than sampling only the first item.

Send-Invoice Subscriptions

The due date and collection process matter in addition to the billing anchor. Verify collection_method and days_until_due.

Past-Due or Unpaid State

Open invoices do not move through Customer Data Copy. Decide whether the seller collects, writes off, or otherwise resolves source receivables, and document what the destination subscription represents.

Billing Dates Too Close to Cutover

Stripe recommends scheduling destination subscriptions after a near-term cycle so the source system can issue the final bill without overlap. Move the operational cutover boundary; do not improvise with an immediate creation.

MoveMRR Review

For each planned subscription, review:

• source and destination Price mapping;
• next expected billing date;
• trial handling;
• proration setting;
• source-deactivation strategy;
• warnings for states that need manual review.

After the run, compare the destination result and exported ID map with the source snapshot. A successful API response is not a complete billing reconciliation.

Related Resources

• Technical Stripe subscription migration guide
• Prevent double billing during migration
• Billing-cycle anchor migration compatibility
• Stripe Billing Migration Toolkit vs MoveMRR
• SaaS acquisition billing handover checklist