Skip to main content

Current product flow · 11 checkpoints

Move every Stripe subscription—without guessing at the cutover

This is the complete MoveMRR operating guide: what to click, why each stage exists, what can go wrong, and what evidence you need before moving forward.

The pipeline

Connect → Catalog → Customers → Configure → Rehearse → Launch → Verify

Hands-on time

About 1–2 hours, plus Stripe processing

Required access

Stripe admin on source and destination

Safe default

Rehearse in Sandbox before Live

?

One decision before you begin

If your Stripe sandboxes already contain realistic subscriptions and catalog data, follow this guide straight through. If they are empty, stop after Connect, use the separate seeding guide, then return to Catalog.

Start the main guideMy sandboxes are empty →
1Before you start

Prepare the two Stripe accounts and choose an environment

A migration is a coordinated cutover between a source account (the seller) and a destination account (the buyer). Naming those roles now prevents the most dangerous mistake later: creating or cancelling objects in the wrong account.

Do this

  1. 1

    Assign an owner on each side

    Keep one person with Stripe administrator access to the source account and one to the destination account available. Both should have two-step authentication enabled and be able to create restricted API keys.

  2. 2

    Choose Sandbox or Live migration

    Start with Sandbox when you want a no-risk rehearsal in Stripe test mode. Sandbox projects are free, use test keys, and require no liability waiver. Choose Live only for the production cutover; it creates real subscriptions, can affect real billing, and uses one migration license.

  3. 3

    Choose a quiet operating window

    Avoid product, pricing, coupon, customer, and subscription changes while the final rehearsal and live run are in progress. If your team must make a change, finish it first and run readiness again.

  4. 4

    Record the destination account ID

    In the destination Stripe Dashboard, copy the account ID beginning with acct_. You will use it when the source account sends the Customer Data Copy.

Continue only when

  • You can switch between both Stripe accounts without losing access.
  • You know which account is source and which is destination.
  • You have decided whether this project is a sandbox rehearsal or the live cutover.

Watch out

A MoveMRR Sandbox project and a Stripe sandbox are related but different: the MoveMRR project connects two Stripe test environments. If those environments are empty, use the optional seeding guide after Connect.

2Project setup

Create the migration project

The project is the permanent workspace for keys, mappings, configuration, rehearsals, runs, audit history, and verification. The seven-stage rail on the left is also your live checklist.

Do this

  1. 1

    Open Migrations

    From the MoveMRR sidebar, select Migrations, then New migration. On an empty account, use Create your first migration.

  2. 2

    Select the environment

    Select Sandbox for test keys and test data, or Live migration for production. This choice controls key validation, licensing, waiver requirements, and what Stripe objects can be touched; it is not a cosmetic label.

  3. 3

    Name the project

    Use a name that identifies both sides, for example “Acme → BuyerCo · Production”. Add the deal date or cutover window in the description so the project remains understandable in the audit history.

  4. 4

    Create the project

    Select Create migration. MoveMRR opens the project at the first incomplete stage. There is no Easy/Advanced mode: every project follows the same pipeline, with recommended actions first and manual controls available when needed.

Create new migration

Continue only when

  • The environment badge says SANDBOX or LIVE as intended.
  • The project name clearly identifies the direction of the migration.
  • The sidebar shows Connect, Catalog, Customers, Configure, Rehearse, Launch, and Verify.
3Stage 1 · Connect

Generate, validate, and store both Stripe keys

MoveMRR needs to read the source account and create mapped objects in the destination. Restricted keys keep that access limited to the permissions required for this migration.

Do this

  1. 1

    Start with the Source account card

    Select Generate. The dialog creates a Stripe deep link with the required permissions preselected. Before opening it, confirm the Stripe account named in the dialog is the seller/source account and confirm Live or Test mode matches the project.

  2. 2

    Create and copy the restricted key in Stripe

    Open the generated Stripe link, review the permissions, create the key, and copy it immediately. Stripe only shows the full secret once. Return to MoveMRR, paste it into the Source field, then select Validate & store.

  3. 3

    Repeat for Destination

    Use the Destination account card and repeat the process in the buyer/destination Stripe account. The destination key needs write permissions because MoveMRR creates products, prices, coupons, subscriptions, and—when selected—Stripe webhook endpoints there.

  4. 4

    Resolve Stripe Connect accounts when prompted

    If a key belongs to a Connect platform, choose the connected account that actually owns the subscriptions. “Acting as the platform account” means no connected account has been selected. Re-enter the key when applying a connected account because stored secrets are never returned to the browser.

  5. 5

    Decide whether to migrate Stripe webhook endpoints

    When enabled, MoveMRR requests the additional endpoint permissions and recreates source Stripe webhook endpoints in the destination at cutover. Each recreated endpoint receives a new whsec_ signing secret that must be deployed after the run.

Connect both stripe accounts

Continue only when

  • Both cards show Stored and Validated.
  • The account IDs shown on the cards match the intended source and destination.
  • Both keys show the correct LIVE or TEST mode.
  • Connect in the stage rail is complete.

Watch out

Never paste a live key into a sandbox project or a test key into a live project. Use Generate from the correct card instead of manually guessing permissions.

Good to know

Keys are encrypted at rest and are not returned to the browser after storage. Access expires inside MoveMRR after 30 days; Rotate resets that expiry, and the account owner still revokes the key in Stripe after the project.

Restricted Stripe key reference →
4Optional branch · Sandbox only

Do your Stripe sandboxes already contain realistic data?

A sandbox migration is useful only when it exercises the same catalog and subscription shapes as production. Seeding is intentionally kept out of the main migration path because many teams already maintain representative sandboxes.

Do this

  1. 1

    If your sandboxes are ready

    Skip seeding and continue directly to Catalog below. “Ready” means the source sandbox has the products, prices, coupons, customers, and subscriptions you want to test, and the destination sandbox resembles the buyer account closely enough to expose mapping conflicts.

  2. 2

    If either sandbox is empty

    Open the Sandbox Seeding workspace from the Connect page. The separate guide covers read-only live-key validation, source and destination seeding, preview counts, entity choices, run results, customer sync, and the generated mapping CSV.

  3. 3

    Return to this guide after customer sync

    The seeding guide returns here. Continue with Catalog; when you reach Customers, use the mapping CSV generated by Customer sync instead of Stripe Customer Data Copy.

Sandbox seeding workspace

Continue only when

  • Source sandbox subscriptions reference realistic source prices.
  • Destination sandbox contains any pre-existing buyer catalog you want to test against.
  • You know whether Customers will use Stripe’s CSV (live) or the generated customer-sync CSV (sandbox).
Open the complete Sandbox Seeding guide →
5Stage 2 · Catalog

Map products, prices, coupons, and promotion codes

Subscriptions point to immutable Stripe price IDs. A destination subscription cannot use the source price ID, so every required source price must resolve to the correct destination price before rehearsal.

Do this

  1. 1

    Read the coverage strip

    Products, Prices, and Coupons show verified mapped/required counts. “Source total unknown” is not zero; run the relevant scan. Do not continue while a required segment is unmapped or could not be verified.

  2. 2

    Run Migrate catalog automatically

    Select the hero action, review the plan, then confirm. MoveMRR creates missing destination products and active prices, records mappings, and handles coupons and promotion codes. Watch each sub-step and inspect the results rather than closing the dialog immediately.

  3. 3

    Review Products

    Confirm that destination products represent the same plans or add-ons. A mapping is an identity decision: two products should map only when they mean the same thing to billing and your application.

  4. 4

    Resolve Prices

    Open Prices and filter for Unmapped. Use Auto-suggest only after checking amount, currency, recurring interval, usage type, tiers, and product. For large catalogs, use Bulk import; otherwise add or edit a mapping manually.

  5. 5

    Resolve Coupons and promotion codes

    Open Coupons, scan the source, and auto-create or manually map remaining items. Run coupon-usage coverage so a coupon used by a migrating subscription cannot be overlooked.

Catalog coverage and auto migration

Continue only when

  • Required product and price coverage is complete.
  • Every mapped price has the same commercial meaning, currency, amount, and interval.
  • Coupons used by migrating subscriptions are covered.
  • Any automatic result marked skipped or failed has been reviewed.

Watch out

Do not map by a similar name alone. “Pro Monthly” can differ by currency, amount, tax behavior, usage type, or interval. Those differences change what customers are billed.

6Outside MoveMRR · Live projects

Copy customers and payment data in Stripe

MoveMRR recreates subscriptions, not card data. Stripe Customer Data Copy transfers the customer and reusable payment-method references securely and produces the old-to-new customer ID mapping MoveMRR needs.

Do this

  1. 1

    Initiate the copy in the source account

    In the source Stripe Dashboard, open Customers, select Copy, then Copy all customers. Enter or choose the destination account ID and submit the request. If the UI differs, use Stripe search for “Copy customers” while staying in the source account.

  2. 2

    Accept in the destination account

    Switch to the destination Stripe account. Open Customers and accept the incoming data-copy request. Verify the banner names the expected source account before selecting Accept.

  3. 3

    Wait for Stripe to finish

    Do not upload a partial or older mapping. Stripe processes the transfer asynchronously; wait until the copy is complete and the Data Migrations document is available.

  4. 4

    Download the mapping CSV

    In the destination account, open Settings → Compliance and documents → My documents. Find the Data Migrations document for this exact source/destination pair and select Download.

Continue only when

  • The destination request names the correct source account.
  • The copied customer count is plausible for the migration scope.
  • The downloaded CSV belongs to this transfer, not a previous migration.

Watch out

Do not open and re-save the CSV in Excel, Numbers, or Google Sheets. Those tools can alter IDs, quoting, encoding, or leading characters. Upload the original Stripe file.

What Stripe Customer Data Copy includes →
7Stage 3 · Customers

Upload and validate the customer mapping

The customer mapping joins each source customer ID to the destination customer created by Stripe. Without a valid row, MoveMRR cannot attach that customer’s recreated subscription or payment method safely.

Do this

  1. 1

    Choose the correct mapping source

    For a live project, use the untouched CSV downloaded from Stripe. For a seeded sandbox project, open Customer sync in the Seeding workspace; its completed run generates and uploads the mapping automatically.

  2. 2

    Upload the CSV

    On Customers, use the upload area to select or drop the file. Wait for Processing to finish. MoveMRR validates the file structure, duplicate IDs, row values, and account compatibility before it marks the upload Valid.

  3. 3

    Inspect the selected upload

    The workspace automatically selects the most recent valid upload. Review row counts and any invalid rows. If you upload a correction, verify the new filename is selected before rehearsal.

  4. 4

    Check payment-method coverage

    Run the payment-method scan. Investigate customers without a usable default payment method now; otherwise their subscription may be created without the payment setup needed for the next renewal.

Customers upload and coverage

Continue only when

  • At least one upload is marked Valid.
  • The mapping count matches the expected customer population.
  • The currently selected upload is the intended file.
  • Payment-method gaps are understood or fixed.

Watch out

Never build a mapping by matching email addresses. Emails are neither unique nor immutable. Use the Stripe-generated old and new customer IDs.

8Stage 4 · Configure

Review the migration behavior—especially source deactivation

Configuration determines what is created, what happens to the seller’s subscriptions, and how billing dates, trials, metadata, and multi-subscription customers behave. The defaults are safe, but they still require an explicit review.

Do this

  1. 1

    Confirm Scope

    Keep Migrate subscriptions enabled for the core migration. Migrate products controls catalog creation. Enable Migrate Stripe webhook endpoints only when you are prepared to deploy the new whsec_ secrets shown after the run.

  2. 2

    Choose source deactivation

    Cancel at period end is the default: the source ends after the already-paid period while the destination preserves the billing schedule. Cancel immediately is a hard cutover and cannot be automatically reactivated by rollback. Pause collection leaves the source subscription present but stops collection. None requires manual deactivation and leaves a double-billing risk until it is done.

  3. 3

    Review Advanced settings

    Atomic multi-subscription handling moves all subscriptions for a customer together or none. Decide whether to copy all, selected, or no metadata; preserve or end trials; and preserve, realign, or restart billing cycles. Preserve is the least surprising option for customers.

  4. 4

    Save or confirm the defaults

    If you changed anything, use the sticky Save bar. If the recommended values are already correct, select Confirm defaults. The stage is not complete until MoveMRR records that you reviewed it.

Configure source deactivation

Continue only when

  • The scope contains only the object types you intend to migrate.
  • The source deactivation consequence is acceptable to both seller and buyer.
  • Billing-cycle and trial behavior match what customers were promised.
  • Configure shows reviewed in the stage rail.

Watch out

Selecting None means both Stripe accounts can bill the same customers until you complete the manual deactivation list on Verify.

How billing anchors preserve renewal dates → Double-billing prevention reference →
9Stage 5 · Rehearse

Validate readiness, dry-run the plan, then simulate

Rehearsal separates “the inputs look complete” from “this exact migration plan behaves as expected.” None of these checks writes production subscriptions.

Do this

  1. 1

    Select Validate readiness

    Readiness checks keys, catalog coverage, customer mapping, configuration, and other launch prerequisites. Expand failed checks, copy the reported object IDs, fix the root cause, then validate again.

  2. 2

    Run a dry run

    The dry run creates the planned action set without executing the migration. Review planned creates, skips, deactivations, warnings, and totals. A surprisingly low count usually indicates scope or mapping problems; a surprisingly high count can indicate an incorrect CSV or account.

  3. 3

    Run the simulation

    Simulation tests subscription creation behavior in a controlled manner and gives you a closer preview of Stripe responses. Review every failure category and follow the links back to Catalog, Customers, or Configure.

  4. 4

    Repeat after changes

    Changing configuration, mappings, keys, or the CSV can make prior readiness evidence stale. Re-run readiness and the dry run after any meaningful change; do not rely on an old green result.

Rehearse readiness dry run simulation

Continue only when

  • Readiness has no failed checks.
  • Dry-run totals match the migration population you expect.
  • Warnings are understood, not merely ignored.
  • The latest rehearsal reflects the current mappings, CSV, and configuration.

Watch out

A dry run is a plan, not proof that every write will succeed. Use both the dry run and simulation, then keep the final live window free from configuration changes.

10Stage 6 · Launch

Clear every gate, confirm the run, and monitor it

Launch is the controlled production boundary. The gate checklist prevents a run from starting with missing evidence, the confirmation shows the exact scope, and the run card remains the source of truth until the operation is terminal.

Do this

  1. 1

    Clear the gate checklist

    Resolve every blocking row: keys, catalog coverage, customer mapping, configuration review, fresh readiness, license, and—for live projects—the liability waiver. Sandbox projects do not require a waiver or license.

  2. 2

    Decide on past-due subscriptions

    Past-due inclusion is selected per run. It is off by default because the open source invoice is voided and billing restarts at the next regular cycle. Include it only after the seller and buyer agree on that accounting treatment.

  3. 3

    Start now or schedule

    Start migration opens the final confirmation. Review customer count, price count, environment, deactivation strategy, dry-run status, and past-due choice. A scheduled run requires confirmation at the scheduled time; keep an authorized operator available.

  4. 4

    Monitor the live run

    Keep the run console open. Progress, Stripe throttling, failures, and safe actions appear on the card. Pause is the safe brake for a live run; do not cancel source subscriptions or edit mappings in Stripe while it is active.

  5. 5

    Acknowledge the terminal result

    When the run finishes, read the outcome and open the run detail for failures. Acknowledging clears the terminal alert from the rail; it does not erase the run or its audit history.

Launch gates and confirmation

Continue only when

  • All launch gates are green before confirmation.
  • The final counts and environment are correct.
  • An operator can monitor until the run is terminal.
  • No one will manually edit source subscriptions during execution.

Watch out

Do not start a second run to “unstick” an active one. Use Pause or the explicit retry/follow-up action offered by MoveMRR after the current run reaches a terminal state.

11Stage 7 · Verify

Reconcile both accounts and complete the cutover

A completed run is not the end of the migration. Verify turns run results into an operational handover: clear failures, reconcile source and destination, deploy new secrets, and confirm renewals reach the buyer account.

Do this

  1. 1

    Read the outcome header and Action queue

    Start with the latest live run. Complete server-derived follow-ups such as retrying failed items, cleanup, scheduled-run actions, payment-method remediation, or rollback when explicitly available. Export the ID map and any manual-deactivation list for your records.

  2. 2

    Generate Reconciliation

    Compare source and destination subscriptions, customers, MRR by currency, and—when selected—Stripe webhook endpoints. Investigate orphans and mismatches. MRR is shown per currency and must not be summed across currencies.

  3. 3

    Fix default payment methods

    Re-scan payment-method status and use the remediation action for customers whose migrated payment method exists but is not the default. Export remaining exceptions for manual work.

  4. 4

    Deploy the application cutover

    Replace the application’s destination Stripe secret and publishable keys, update product/price IDs where your code stores them, change Customer Portal and Connect references, and deploy each new whsec_ signing secret before relying on recreated endpoints.

  5. 5

    Monitor real renewals

    Watch the first renewal cohort in the destination account, confirm source deactivation follows the chosen strategy, monitor webhook delivery, failed payments, support tickets, and MRR. Keep the project and audit exports as the migration record.

Verify action queue and reconciliation

Continue only when

  • The Action queue contains no unresolved server-derived follow-ups.
  • Reconciliation succeeds or every mismatch has an owner and written explanation.
  • Application keys, price references, portal links, and webhook secrets point to the destination.
  • A sample of upcoming renewals has succeeded in the destination account.

Watch out

Do not delete or archive the source account immediately. Keep it accessible through at least the agreed verification window so you can inspect invoices, cancellations, disputes, and reconciliation evidence.

Final handover

The migration is done when the evidence agrees

A green run status alone is not enough. Treat the migration as complete only when the run results, action queue, reconciliation report, destination configuration, webhook delivery, and real renewals tell the same story.

Common questions

Do I still need to choose Easy or Advanced Mode?

No. The mode split was removed. Every migration uses the same seven-stage pipeline. Recommended actions appear first, while manual mapping and advanced configuration remain available inside the relevant stage.

Is Sandbox Seeding required?

No. Skip it when your Stripe sandboxes already contain representative data. Use it when an empty sandbox would make your rehearsal meaningless. Seeding is available only for MoveMRR sandbox projects.

Can MoveMRR copy card data?

No application should handle raw card data during this process. For live migrations, Stripe Customer Data Copy transfers customer and reusable payment-method references. For sandbox testing, customer sync creates customers with Stripe test payment methods.

What should I do after changing a mapping or configuration?

Return to Rehearse and validate readiness again. Then create a fresh dry run. Launch evidence must describe the current keys, CSV, mappings, and configuration—not an earlier version of the project.

When is the migration truly finished?

When the run is terminal, the Verify action queue is clear, reconciliation is accepted, application keys and webhook secrets are deployed, and the first real renewals have succeeded in the destination account.

Open MoveMRR and keep this guide beside it

The stage rail tells you where you are. This guide tells you why each decision matters before you make it.

Open MoveMRR →