July 24, 2026 Updated: July 24, 2026 By MoveMRR Team

Stripe Subscription Migration Cutover Runbook

Direct answer: A Stripe subscription migration cutover should run like a controlled production release. Freeze the in-scope billing state, create or schedule destination subscriptions, verify their configuration, stop source collection before an overlapping charge, deploy the buyer’s account-specific application configuration, reconcile every row, and monitor renewal cohorts. Every irreversible action needs a named owner, evidence, and a stop condition.

This runbook uses T0 for the agreed moment when the destination becomes the operational billing system. Adjust the calendar to the actual renewal distribution and Stripe workflow. Do not force a migration into a date that leaves no time for Stripe review, data preparation, validation, or customer remediation.

What This Runbook Covers

The runbook coordinates four systems that must agree:

Source Stripe account: the existing subscription population, invoices, and deactivation actions.
Destination Stripe account: copied Customers, mapped catalog objects, and recreated subscriptions.
SaaS application: API credentials, Stripe IDs, webhooks, portal links, and entitlements.
Operating team: buyer, seller, engineering, finance, support, and the person authorised to stop the run.

It does not decide whether a migration is legally required. First choose between account retention and cross-account recreation using the SaaS asset-sale vs share-sale decision guide.

Name the Cutover Roles

Assign people, not departments:

Role	Decision authority
Cutover lead	Owns the clock, opens gates, pauses the run, and records decisions
Seller billing owner	Confirms source scope, freeze, invoices, and source deactivation
Buyer billing owner	Confirms destination account, settings, mappings, and subscription state
Application owner	Deploys credentials, object mappings, webhooks, portal, and entitlements
Reconciliation owner	Compares source snapshot, destination results, and financial totals
Customer-remediation owner	Handles missing payment methods, authentication, and support cases
Transaction approver	Accepts residual exceptions under the signed handover terms

No one should approve their own high-risk output without an independent verifier. For smaller teams, one person can hold multiple roles, but the evidence and second-person review should remain.

Create the Evidence Pack Before T−30

Use one controlled location for:

source and destination Stripe account IDs;
Stripe Support confirmation of the account and customer-data path;
in-scope query or export definition;
source snapshot hash, time, and row count;
Customer and payment-data copy result;
Product, Price, Coupon, tax, and subscription mapping tables;
dry-run and sandbox results;
subscription old-to-new ID map;
source-deactivation result;
application deployment and webhook test evidence;
exception register with owner and deadline;
buyer/seller go/no-go decisions;
first-renewal reconciliation.

Do not put Stripe secret or restricted API keys, webhook signing secrets, raw payment details, or customer-sensitive exports into a general deal folder. Stripe’s API-key best practices recommend least privilege, secure storage, access restrictions, and rotation.

T−30 to T−14: Decide the Path and Remove Unknowns

Account and data gates

Confirm with Stripe whether the existing account can remain with the business.
If a destination account is required, confirm its legal entity, country, payout details, tax settings, statement descriptor, receipts, and team access.
Ask Stripe which Customer and payment-method data can be copied.
Define the exact subscription population included in the transaction.
Separate excluded products, test data, canceled records, and subscriptions owned by a retained business.

Stripe says its account-copy process can copy eligible Customer and supported payment data, but not subscriptions, invoices, plans, coupons, events, or logs. Review the live data-copy matrix rather than assuming every payment method will arrive.

Billing-model inventory

Count and classify:

monthly, annual, and mixed intervals;
multiple subscription items and quantities;
trials and future schedules;
automatic collection and send-invoice subscriptions;
discounts and promotion behavior;
automatic tax and fixed tax rates;
metered or usage-based items;
paused, past-due, unpaid, and cancel-at-period-end states;
custom billing anchors, prorations, credits, and pending invoice items.

Use the compatibility guides for billing-cycle anchors, multi-item subscriptions, Stripe Tax, and metered billing to assign a treatment to each cohort.

Application inventory

Find every account-specific dependency:

server and publishable API keys;
Customer, Subscription, Product, Price, Coupon, and Tax IDs;
webhook endpoint configuration and signing secrets;
Customer Portal configuration;
scheduled jobs and background reconciliation;
database entitlements and subscription status rules;
support, analytics, warehouse, tax, and accounting integrations.

T−14 gate: Stop if the account path is unconfirmed, the population cannot be reproduced, or a material billing cohort has no destination treatment.

T−14 to T−7: Rehearse the Exact Work

Run a representative sandbox migration that includes ordinary and difficult cohorts. Stripe’s API migration guide recommends testing the pricing-model import in a sandbox and notes that sandbox and live-mode IDs must be mapped separately.

The rehearsal must prove:

destination Customers resolve and automatic-collection cases have a usable default;
destination Price, Coupon, and Tax IDs belong to the destination account;
billing amounts, currencies, intervals, quantities, trials, and next charge dates match the approved treatment;
application code resolves the resulting destination IDs;
destination webhook signatures verify;
duplicate and out-of-order events do not corrupt entitlements;
source-deactivation behavior is understood before it is used live;
every unsupported case enters a visible remediation queue.

Stripe does not guarantee webhook event order. Its webhook documentation instructs integrations to verify signatures and retrieve missing objects when necessary. Do not use receipt of one event as the only proof that a migrated subscription is correct.

T−7 gate: Stop if the rehearsal cannot be reproduced, webhook verification fails, or the team cannot reconcile expected and actual results at field level.

T−7 to T−3: Lock the Run of Show

Publish a minute-by-minute run sheet with:

migration batch order;
exact subscription filters;
operator and independent verifier for each action;
destination start or go-live time;
source billing boundary;
application deployment window;
customer-change freeze start and end;
support coverage;
stop conditions;
escalation contacts;
the latest reversible point.

Group subscriptions by operational risk, not arbitrary row count. A sensible batch structure might separate simple monthly automatic collection, annual subscriptions, trials, send-invoice customers, complex schedules, and owned exceptions.

If the operation uses Stripe’s Billing migration toolkit, review the current toolkit specification. Stripe currently requires production start_date values at least 24 hours in the future, validates the upload, creates Subscription Schedules, holds them in a scheduled state for 24 hours, and displays a 10-hour toolkit cancellation window. Record the actual cancellation deadline shown in the Dashboard.

T−3 gate: Stop if the selected date conflicts with upcoming source renewals, the toolkit timing, a deployment freeze, or support availability.

T−72 Hours to T−24 Hours: Take the Final Snapshot

Announce the subscription-change freeze to the operating team.
Disable or tightly control upgrades, downgrades, cancellations, trial changes, coupon changes, and admin edits for the in-scope population.
Capture the final source export and its exact timestamp.
Re-run the scope definition and compare it with the prior rehearsal input.
Reconcile destination Customers and payment-method readiness.
Rebuild live destination mappings; never reuse sandbox IDs.
Run the final no-write readiness check.
Upload or prepare the approved migration batches.
Record validation errors without editing the source snapshot in place.
Resolve errors through a versioned correction file and repeat validation.

For an initial readiness pass, use the browser-only Stripe migration readiness assessment. It does not upload Stripe credentials or replace field-level reconciliation.

Snapshot-change rule

Any in-scope source change after the snapshot must have one of three outcomes:

reverse the change before T0;
add it to the migration input and repeat affected checks; or
record it as an owned post-cutover exception.

Silent drift is not an acceptable fourth option.

T−24 Hours to T−1 Hour: Verify the Scheduled State

For every batch, compare the destination output with the approved source treatment:

Field group	Required comparison
Identity	Source Customer and Subscription IDs mapped to actual destination objects
Commercial terms	Currency, recurring amount, interval, quantity, and items
Timing	Destination start, next expected invoice, trial end, and cancellation state
Collection	Automatic collection or send invoice, days due, and default readiness
Adjustments	Coupon, tax treatment, pending items, credits, and proration decision
Application	Local tenant, entitlement, portal, and webhook mapping
Control	Batch ID, operator, verifier, timestamp, and exception status

Counts are necessary but insufficient. Equal source and destination counts can hide a wrong annual price, shifted billing date, missing second item, or mismatched tax behavior.

Inspect the source invoice boundary

Before source deactivation, inspect open and draft invoices, pending invoice items, metered usage, scheduled cancellations, and renewals around T0. Stripe’s subscription cancellation documentation explains that cancellation timing can affect invoices, pending items, usage, prorations, and collection. Choose the action per cohort; do not apply one cancellation assumption to every subscription.

T−1 gate: Stop if any account-wide mismatch exists, any high-value exception lacks approval, or the source and destination could collect for the same service period without an owned resolution.

T0: Execute the Cutover

The cutover lead reads each control aloud and records its evidence:

Confirm the source-change freeze is still effective.
Confirm the migration input matches the final approved snapshot.
Confirm destination schedules or subscriptions exist with the agreed start state.
Retrieve a representative sample directly from the destination account.
Confirm the application release is ready with destination credentials and object mappings.
Confirm destination webhook signature verification and event handling.
Confirm the Customer Portal and payment-update paths point to the destination account.
Complete the approved source-deactivation action before a source charge can overlap the destination billing boundary.
Re-query both accounts and compare the final source and destination state.
Release the application deployment and subscription-change freeze only after the verifier signs off.

Stripe advises creating the destination subscriptions before canceling the old subscriptions, while canceling the old subscriptions before the new subscriptions are set to charge. For a billing date close to migration, Stripe recommends scheduling the destination after that cycle so the old system produces the final bill. That guidance appears in the Billing migration toolkit documentation.

The exact order of application deployment and source action depends on the architecture. The invariant is that the product must resolve the intended destination account when destination billing becomes authoritative.

The Go/No-Go Board

Gate	Go evidence	No-go condition
Account	Destination account ID and Stripe path confirmed	Entity, country, or ownership path unresolved
Scope	Reproducible snapshot and approved exclusions	Population changed without reconciliation
Customer data	Eligible copy reconciled; exceptions assigned	Unknown or unusable defaults in an unowned cohort
Catalog	Every required destination mapping verified	Source IDs used where destination IDs are required
Billing	Amounts, timing, tax, trials, collection, and cancellation match	Material field mismatch
Application	Keys, IDs, webhooks, portal, and entitlements tested	Application still depends on source-only configuration
Source boundary	Action and time approved per cohort	Both accounts can collect the same period
Recovery	Latest reversible point and remediation owners recorded	Team calls an irreversible action “easy to roll back”

Only the cutover lead changes the board. A deadline, senior stakeholder, or sunk migration effort does not convert a no-go condition into a go.

Understand the Rollback Boundary

“Rollback” means different things at different points:

State	Available response
Before destination creation	Correct input and repeat readiness checks
Destination schedules created, source untouched	Cancel or correct destination schedules within the applicable Stripe path and verify the result
Toolkit migration within its displayed cancellation window	Use the documented toolkit cancellation path, then confirm no destination schedule can activate
Toolkit window elapsed, schedules not live	Follow Stripe’s documented API or individual cancellation path and verify every schedule
Destination live, source still recoverable	Pause the run and choose the safer billing system before any overlapping charge
Source subscription canceled	Treat recovery as remediation, not a simple rollback

Stripe states that a canceled subscription cannot be reactivated. A new subscription must be created if service should resume. Never cancel the source population merely to make a dashboard count look complete.

If an internal API workflow creates objects, use stable per-row idempotency keys and persist the resulting Stripe IDs. Stripe’s idempotent-request documentation explains how identical retries avoid duplicate side effects. Idempotency does not verify that the original parameters were commercially correct; reconciliation still does that.

T+1 Hour to T+24 Hours: Stabilise

Monitor and record:

unexpected source invoices or collection attempts;
destination schedule activation and subscription status;
invoice.paid, invoice.payment_failed, and invoice.payment_action_required;
webhook signature failures, retries, duplicates, and processing latency;
entitlement changes and account-access complaints;
portal or payment-update requests hitting the wrong account;
discrepancies in subscription count and recurring-value totals;
new exceptions from missing defaults, declines, or authentication.

Stripe’s subscription webhook guide documents payment-failure and authentication-required events. These cases are why “no customer action” must remain an observed outcome, not a blanket promise.

Keep support messaging factual. Tell an affected customer what needs attention without describing the entire population as impacted.

T+2 Days to T+7 Days: Reconcile Renewal Cohorts

Reconcile by expected renewal window:

list destination invoices expected in the window;
compare paid, open, failed, action-required, and uncollectible outcomes;
search the source account for any invoice covering the same service period;
compare entitlement state with the paid and subscription state;
assign every mismatch to an owner;
record customer contact only where a real case requires it;
update the signed exception register.

An active subscription alone is not proof that every invoice is paid. Stripe’s subscription lifecycle documentation explains how subscription, invoice, and PaymentIntent states interact.

T+8 Days to T+30 Days: Close the Handover

Close the project only when:

all in-scope rows are migrated or have an accepted exception;
the old-to-new ID map is stored with the buyer’s operating records;
source deactivation and residual invoices reconcile;
first-renewal cohorts match the expected destination behavior;
customer-remediation cases have an owner and outcome;
seller access and migration credentials follow the agreed rotation schedule;
support, finance, and engineering accept the operational handover;
legacy source access meets the transaction’s record-retention plan.

Use the transparent State of Stripe Account Migrations 2026 research as a benchmark reference, not as a substitute for your own reconciliation. Its methodology states the size and limits of the observed MoveMRR customer set.

Frequently Asked Questions

When should source subscriptions be canceled?

At the approved billing boundary, after destination objects are verified and before both systems can collect for the same service period. Immediate, period-end, and custom cancellation can have different invoice, usage, and proration effects, so choose per cohort.

Is the Stripe toolkit’s 24-hour scheduled state a rollback window?

It creates review time, but the Dashboard toolkit’s documented cancellation window is currently 10 hours. Record the deadline shown for the actual migration and independently verify any cancellation.

Does a matching subscription count prove success?

No. Reconcile amount, currency, items, quantity, next billing date, trial, collection method, discount, tax, state, payment readiness, and application mapping.

Can every customer remain passive?

No universal promise is supportable. Eligible data may copy successfully, but missing defaults, unsupported methods, future issuer declines, or authentication can still require action.

What should happen if the run misses T0?

Keep the last verified billing system authoritative, prevent overlapping collection, record the new snapshot, and reschedule with the affected checks repeated. Do not compress an expired control window into an unreviewed live action.

Official Stripe Sources

Next Step

Run the readiness assessment, review the Stripe toolkit comparison, and use the SaaS acquisition workflow to turn the runbook into a buyer/seller migration project.