Embed Migration Manual

1. October 1, 2026Shopify rejects new script tags on every API version"This app can't create or update script tags. Use theme app extensions instead."2026-10-01
2. January 1, 2027The Admin API rejects non-expiring offline access tokensApps must use expiring offline tokens with refresh.2027-01-01
3. March 1, 2027Shopify stops injecting script tags on storefrontsAnything still loaded by a script tag stops running.2027-03-01

Why stores must change

Since October 1, 2026, no app can create or update a script tag. The kit asks Shopify for one on every store as a live proof, and the answer is always the same refusal. From March 1, 2027, Shopify stops loading the script tags that already exist. On that day, any currency selector or price logic that still depends on a script tag disappears from the storefront without an error.

The modern replacement has two parts:

• A theme app embed that loads our code inside the merchant's theme. The merchant switches it on once, per theme.
• Shopify Markets for prices. The buyer picks a country, and Shopify prices the store on the server. No exchange rates, and no price rewriting in the browser.

The work for each store is the same five stages: Measure, Activate, Verify, Remove and, only when the store fakes local prices with one variant per country, Prices by country.

Legacy code runningEmbed running

Show all: Legacy code runningHalf and halfShow all: Embed running

Who does what

Two steps always belong to the merchant: switching the embed on, and approving any change to their theme. The platform requires the first. The second is our rule.

Three signals, three statuses

"Enabled isn't running." A merchant can switch the embed on and the storefront can still not run it. The kit only calls a store verified when three signals agree:

The kit combines the signals with what's left of the old integration and shows one store status:

Try it: set the signals the way you see them in a store, and the decoder shows the status the app will show and what to do next. It uses the same rules as the app.

The app at a glance

Open the store admin → Apps → Embed Migration Kit. The app is one page. Click any part of the map to jump to its stage in this manual.

123456789

The button Re-scan store sits in the admin's title bar, at the top right of the app. Click it after every change you make outside the app: a theme edit, a storefront visit, a new market.

Before you start

Check every item before you open the app. Each one has stopped a migration before.

Stage 1 · Measure

Goal: know everything the old integration left behind in this store.

Do

1. Open the section 1 · Measure.
2. Read the three numbers: script tags registered, legacy markers in the live theme and themes scanned. Write them in the checklist.
3. Read the table under each theme that has markers: File (file and line), What and Code.
4. Optional, for the merchant or your lead: click Ask Shopify to create a script tag (live proof).

The kit scans layout/theme.liquid, snippets/* and sections/* in every theme (up to six). These are the legacy markers it knows:

Stage 2 · Activate

Goal: the embed is switched on in the live theme.

An app can't switch an embed on by itself. A person has to click it in the theme editor, normally the merchant. The kit opens the editor on the right theme with the embed ready.

Do

1. Open the section 2 · Activate. There is one row per theme: Theme, Role (Live or Draft), Embed (settings_data.json), Legacy markers, Last beacon and Action.
2. On the Live row, click Activate embed. It opens the theme editor on that exact theme, by its ID. If the merchant does this step, copy the link and send it with Template A.
3. In the theme editor, under App embeds, find Currency switcher (Embed Migration Kit) and switch it on.
4. Leave the settings like this: Position as the merchant prefers (Bottom left or Bottom right), Neutralize legacy currency code left in the theme on, Report to the app that the embed is running on.
5. Click Save. Go back to the app and click Re-scan store.

Embed states you can see in the table:

Manual path if the link doesn't work: Online Store → Themes → Customize (on the live theme) → App embeds → "Currency switcher" → On → Save.

Stage 3 · Verify

Goal: prove the embed is running on the storefront, not only enabled.

Do

1. Open the storefront once, any page. This sends the beacon. If the store has a password page (development stores do), enter the password first.
2. Look at the storefront: the Ship to selector appears in the corner the merchant chose, and the old currency pickers are gone.
3. Go back to the app, click Re-scan store and read the banner and the section 3 · Verify.

You should see the banner Store status: Active (or Removed) with the reasons "Embed enabled on the live theme (settings_data.json)" and "Storefront beacon received recently". In the beacon row: when it arrived, the page, and how many legacy elements the embed neutralized.

document.documentElement.dataset.emk   // "running"
window.__emkEmbed                       // { version: "1.0.0", neutralized: 14, … }

Stage 4 · Remove

Goal: delete this app's script tags, one at a time, only after verification. Then the theme cleanup, by a person, with written approval.

Do

1. Open the section 4 · Remove.
2. Click Queue script tag removal. It only works when the store is verified and has script tags. Otherwise you read "Removal stays locked until all three signals are green."
3. Click Run queue now. Each click processes up to 10 jobs that are due. Read the table: Script tag, Status, Attempts, Note.
4. If a job shows retry, click Run queue now again later. The app waits on its own before it retries.
5. Read the Theme cleanup checklist. Each line has the file, the line and what it is, and says either "Already neutralized by the embed on the storefront." or "Not neutralized yet: activate the embed first."
6. Send the checklist with Template B. Clean only a duplicated, unpublished theme. The merchant publishes it.

Queue statuses:

Stage 5 · Prices by country

Do this stage only if the store fakes a local price with one variant per country: an option such as "Country" with values like United States and Mexico. Under Markets, the old variant's local price gets converted again, so the buyer sees a wrong price.

Do

1. Open the section 5 · Prices by country. The first table lists the products with one variant per country: Product, Option, Countries, Stock split by country, Variants.
2. If you read "No active market with its own currency for: …", ask the merchant to create that market in Settings → Markets first.
3. For each market, read the plan: the market, its catalog, the price list in the market's currency, the number of fixed prices (sent in batches of up to 250) and the audit.
4. Read the second table: Variant that stays, Legacy variant, Fixed price to set, Shopify charges in … and Audit.
5. Click Migrate prices (market name). Wait for the banner "Prices migrated for …" and its log.

You should see "✓ fixed price applied" in the Audit column for every row. The migration is safe to repeat: the button changes to Run the … migration again and reuses the catalog and the price list.

Ship to United StatesShip to Mexico

Show all: Ship to United StatesHalf and halfShow all: Ship to Mexico

Left for the merchant (the kit never deletes variants or products): check open orders, remove the legacy variant, move its stock back to the variant that stays and, when no legacy variants are left, remove the "Country" option.

Tokens and report

Tokens · January 1, 2027. The card shows one of two banners:

• "This app uses an expiring offline token" (green): ready for January 1, 2027. Nothing to do.
• "Non-expiring offline token" (red): Shopify rejects these from January 1, 2027. It's an app-level change: escalate.

Report. Click Download JSON and Download CSV. The files are named migration-<store>.json and migration-<store>.csv. Add the CSV to the migration board.

Messages to the merchant

Fill in the fields once. Both messages update as you type. Copy, paste into your email and send.

Hi [Merchant name],

Shopify is retiring the old way apps load on storefronts. From March 1, 2027 it stops loading "script tags", and the currency selector on [Store name] still uses the old method.

We moved the selector to Shopify's new method, called an "app embed". Shopify only lets the store owner switch it on, so we need one click from you:

1. Open this link while you are logged in to your Shopify admin: [Activation link]
2. Make sure "Currency switcher" is on.
3. Click Save.

That's all. We check your storefront afterwards and confirm that everything works before we remove anything old.

Thank you,
[Your name]

Hi [Merchant name],

The new currency selector is running on [Store name], and it already hides the old code on your storefront. Your theme still has [Number of lines] old lines of code from the previous setup:

[Cleanup checklist]

We would like to remove them. This is how we work:

1. We make a copy of your live theme and clean only the copy.
2. We send you a preview link so you can check it.
3. You publish the clean copy when you are happy with it. Your current theme stays as a backup.

Please reply "Approved" to this email so we can start. Nothing changes on your live theme without your approval.

Thank you,
[Your name]

Per-store checklist

One checklist per store. Type the store's name, tick as you go, and copy it into the store's ticket when you finish. Each store keeps its own ticks in this browser.

Troubleshooting

Type what you see. The table filters as you type.

What the kit can't do

Say these limits early, to the merchant and to your team. The app shows the same list on its right-hand column.

• Switch the embed on for the merchant. The platform requires their click. The kit opens the right theme.
• Rewrite theme code from a public app. There is no write_themes, and Shopify doesn't grant that exemption to public apps in general. Cleanup is human, on a duplicated theme, with written approval.
• Delete script tags on frozen (402), locked or closed stores. They are listed with the cause.
• Run in bulk across stores. Bulk operations are per store, and the queue is per store by design.
• Charge in the local currency without Shopify Payments or Adyen. Rounding works only with Shopify Payments.
• Delete legacy country variants. The merchant decides, after checking orders.

When to escalate

Handle everything else with this manual. Call the lead developer only when:

Do

1. The live proof says "Shopify created the script tag".
2. The embed is Enabled, you visited the storefront, the beacon setting is on, and document.documentElement.dataset.emk is not "running".
3. The embed state is Unreadable.
4. The token card is red: "Non-expiring offline token".
5. A queue job is failed, or 401/403 token rejected comes back after the merchant re-authenticated.
6. "Migration for … stopped" shows an error you can't match in Troubleshooting.
7. The theme cleanup needs more than removing the lines in the checklist (custom code around them).

The migration board

Every store gives one report. Merge the CSV files of all stores into one sheet: that's the migration board. The tool below does it in your browser. Drop or paste CSV files, and it shows one row per store. It opens with the development store's real report as an example.

The CSV columns:

Useful views: filter section = verdict to see every store's status in one column; count section = script_tag per store to see what's left to delete; group unreachable stores into frozen (402), locked (423, temporary) and closed (404). Deleting is rarely the bottleneck. The state of the stores is.

Knowledge check

Ten questions. Answer them before your first store on your own. 8 out of 10 is a pass.

Glossary

About this manual

• Photos. Every photo of the storefront and of the app was taken with Playwright on October 13, 2026, on a Shopify development store with test data, after a full run of the five stages. The app photos are the app's own page, built from its own code with that store's real data, rendered outside the admin frame. That's why the admin's title bar, with Re-scan store, isn't in them. The theme editor photo was taken by hand, because the admin needs the merchant's login.
• Nothing identifies a store. The store name reads "Your store" and IDs are generic. No merchant data appears.
• Timings. The kit's own work for one store takes minutes. Most of the time is waiting for the merchant: the activation click and the written cleanup approval. Real merchant timings aren't measured yet; write yours in the report.
• Versions. Embed Migration Kit with the embed "Currency switcher", Admin API 2026-10.
• Edition. 1.0, October 13, 2026. First edition, built on the Embed Migration Runbook (same stages, labels and escalation cases). Send corrections to the lead developer: the next edition keeps this structure.