The migration dry run: rehearsing a cutover

Three things get called a dry run and only one of them is. A staging store with the catalogue loaded is a build; it tells you the theme renders and the integrations connect. A UAT round is a test of behaviour; it tells you whether the store does what was specified. Both are necessary and neither tells you anything about the cutover.

A cutover is a different kind of object: a sequence of operations, performed once, in order, under time pressure, by people who may have been awake for fourteen hours, during which the business cannot trade. Its failure modes are time, ordering and human error — not defects. A step that takes forty minutes instead of the five somebody estimated is a failure even though nothing is broken.

So the rehearsal has to reproduce the properties that matter: real production data volumes rather than a sample, the actual scripts rather than a description of them, the actual people rather than whoever is free, and a clock running. Everything else — the exact time of day, the real DNS switch — can be simulated. Volume, sequence and personnel cannot.

Do it at least twice. The first rehearsal exists to produce the list of things nobody had thought of, and it will always overrun. The second exists to prove the corrected runbook holds. If the second one produces a new list as long as the first, you are not ready, and the honest response is to move the date rather than to hope.

For most replatforms the longest single block of the cutover is loading the delta: everything that changed between the bulk load you did in advance and the moment you froze the old store. Estimating that block rather than measuring it is the most common reason cutovers overrun.

If you are loading through the Admin API’s bulk operations, several documented constraints shape the plan and each one is worth checking against your own data rather than assuming:

The input file is JSONL and capped at 100MB, with one input per line regardless of how nested the object is. A catalogue with long descriptions and many metafields reaches that cap sooner than people expect, which means chunking — and chunking is a thing to rehearse, because the failure mode is discovering it at two in the morning.

Operations have a 24-hour timeout. Not a constraint on cutover night itself, but it disciplines the initial bulk load you do beforehand.

Concurrency changed. Shopify documents that from API version 2026-01 an app can run up to five bulk mutation operations per shop at the same time, where earlier versions permitted one operation of each type per shop. If your import tooling was written against the older behaviour it is probably serialising work it no longer has to, and the rehearsal is where you find out whether parallelising actually shortens the window or simply moves the bottleneck onto your own transform step.

Lines are not processed in order. Shopify is explicit that you cannot depend on execution order to achieve a result. Anything with a dependency between records — variants needing their product, metafields needing their owner, customers needing to exist before their orders — must be separate, sequenced operations. Rehearsal is how you learn that your four operations are really six.

Time each phase separately: export, transform, upload, run, verify. A single total tells you nothing about which part to optimise when the number comes back too large.

A few things genuinely cannot be performed twice, and the dry run’s job is to force a decision about each rather than to practise it.

DNS. You will not point the domain during a rehearsal. What you can do is lower the TTL days in advance so the real switch propagates quickly, confirm who holds the registrar credentials and that they are awake, and rehearse everything up to the switch and everything after it.

Payments in live mode. A rehearsal environment cannot take a real card, so the live payment check becomes the first item in the post-switch verification list: one real order, one real refund, by a named person, before anything is announced.

Customer passwords. These are not a rehearsal problem but a communications one, and they surprise people late. Shopify states plainly that because passwords are encrypted outside Shopify you cannot migrate them from another store using a CSV, and that you need to invite customers to create new ones. That is an email to your entire customer base, with copy that needs writing, approval and a sending plan, and a support queue that will spike for a week. Decide the wording and the send time during the rehearsal, not on the day.

Gift cards and store credit. Outstanding balances are a liability you are legally holding. giftCardCreate allows the code to be supplied rather than generated, which means existing codes can be carried across with the write_gift_cards scope, but the reconciliation — balance by balance — is a finance sign-off. Rehearse producing the reconciliation report, because that is the artefact somebody has to approve.

Redirects. The URL map is usually the largest single SEO risk in a replatform and it has a specific mechanism: a CSV staged upload, urlRedirectImportCreate, then urlRedirectImportSubmit to actually run it. Rehearse the import at full size and then sample the result — a few hundred URLs across every template type, checked for a single hop to a live 200, not a chain and not a soft 404.

The rehearsal produces a duration, and the duration has a cost you can calculate from your own order data: orders per hour at that time of day and day of week, multiplied by the window, multiplied by average order value. Use your own figures and nobody else’s.

That number is what turns an engineering discussion into a business one. A six-hour window at three in the morning on a Tuesday in February is a rounding error for most merchants. The same six hours on the first Saturday of a sale is a different conversation, and the value of the rehearsal is that both parties are now arguing about a measured number rather than a feeling.

It also tells you what is worth optimising. If the measured window is ninety minutes, spending a fortnight halving the import time buys you forty-five minutes at three in the morning. That is a fortnight better spent on the verification checklist.

Nearly every migration plan contains a line reading “roll back to the previous platform if required”. Very few contain the six steps that entails, and almost none have ever been performed.

Rehearse it properly and the awkward questions surface early. Is the old platform still running, or was the server decommissioned to save money? Has it kept taking orders, and if not, what is its state? Orders placed on the new store during the window you are unwinding — where do they go, and who tells those customers? How long does the DNS change take to come back, given the TTL you set?

That last one is the sharp edge. Rollback is not free and it gets more expensive by the hour, which is why the runbook needs a stated decision point — a time by which, if the verification list has not passed, you go back rather than press on. Agree it in the rehearsal while everybody is calm. Nobody makes that call well at four in the morning with a half-migrated store and a marketing email already scheduled.

Skipping the rehearsal because the build is late. This is the single most common way a migration goes badly, and the logic is always the same: the rehearsal is the only item on the plan with no visible deliverable, so it is the one that gets cut. What gets cut with it is the measurement of how long the shop will be closed.

Rehearsing with a sample of the data. A tenth of the catalogue runs in a tenth of the time and tells you nothing about the file size cap, the rate limits or the step that degrades non-linearly. Use the full export.

Treating the rehearsal as a test the agency has to pass. It is meant to produce failures. A dry run where nothing goes wrong is usually a dry run that was not run properly, and the incentive to present a clean one is exactly what makes the real cutover dangerous. Ours are run to find problems, which is also why we would rather talk about the rehearsal before the build than after — it is part of how we scope [replatforming work](/services/migrate) rather than a contingency at the end of it.

Cutting over the week before a peak. Even a well-rehearsed migration needs a watching period afterwards, and peak removes it.

• Shopify migration services
• Migrating a store mid-season, and why you usually should not
• Bulk operations: changing ten thousand products safely