Embed Migration Runbook

Move one merchant store from script tags and legacy theme code to a theme app embed, and prove it works before you remove anything. This runbook is for any developer or support engineer. You don't need to know the kit's code.

Prepared by David · October 2026 · Embed Migration Kit

1. Who this is for and what you get

Who: a developer or support engineer who migrates merchant stores one at a time. You follow the steps, read what the app shows, and you only call the lead developer in the cases listed in section 7.

At the end of one store you have:

• The app embed switched on in the live theme and running on the storefront (three signals green).
• This app's script tags deleted, or listed as unreachable with the cause.
• A cleanup checklist for legacy theme code (file and line), approved in writing by the merchant.
• If the store sells one variant per country: fixed prices per market, checked with an audit.
• A JSON and a CSV report for the migration board.

How long it takes: the kit's own work for one store takes minutes. Most of the time is waiting for the merchant: the activation click (Stage 2) and the written approval for theme cleanup (Stage 4). The full flow has run end to end on one development store (October 10, 2026). Real merchant timings are not measured yet: write yours in the report.

Why now: three dates, not two.

2. Before you start

Check every item before you open the app.

1. Access to the store. Use a collaborator account, not a shared login. Any theme cleanup is done by a person, on a duplicated theme, with written approval.
2. The app is installed on the store, and the app version with the embed is released. A new app version takes several minutes to reach stores.
3. Scopes. The app needs read_script_tags, write_script_tags and read_themes. For prices by country it also needs read_products, write_products and read_markets. It never asks for write_themes. Keep write_script_tags until the audit reads zero script tags in every reachable store. One developer had 107 stores that re-authorized without that scope, and their tags could no longer be deleted.
4. Markets. The country selector appears only when the store has at least two markets (Settings → Markets). With one market the embed still runs and reports, but there is nothing to choose.
5. Written consent from the merchant before any theme cleanup or variant removal. The kit never deletes theme code, variants or products.
6. A duplicated, unpublished copy of the live theme, for any cleanup.

3. The five stages for one store

Open the store admin → Apps → Embed Migration Kit. At the top you see a banner "Store status: …" and, on the right, the button Re-scan store. Click Re-scan store after every change you make outside the app.

Stage 1 · Measure

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

Do:

1. Go to the section 1 · Measure.
2. Read the three numbers: script tags registered, legacy markers in the live theme and themes scanned.
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).

You should see:

• Each marker with its file and line. The kit scans layout/theme.liquid, snippets/* and sections/* in every theme.
• After the live proof: a banner "Shopify refused the script tag" with Shopify's own message.

The kit finds these legacy markers:

The Script Tag API only returns this app's own script tags. The kit can't see or touch tags from other apps.

Stop if: the live proof shows "Shopify created the script tag". That means the platform behaves differently from what this runbook expects. Escalate (section 7).

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 must click it in the theme editor, normally the merchant.

Do:

1. Go to the section 2 · Activate. The table has 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, with the embed ready to switch on. If the merchant does this step, send them Template A (section 4) with this link.
3. In the theme editor, under App embeds, find Currency switcher (Embed Migration Kit) and switch it on.
4. Leave the three settings like this: Position (Bottom left or Bottom right, as the merchant prefers), Neutralize legacy currency code left in the theme: on, Report to the app that the embed is running: on.
5. Click Save.

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

You should see: back in the app, after Re-scan store, the Live row shows Enabled and its button changes to Open in editor. The other embed states are Disabled, Not added yet (never switched on) and Unreadable.

Stop if: the editor opens a theme that is not the live one. Close it and use the manual path on the live theme. The kit builds the link by theme ID because the official themes/current link has opened the draft theme after a theme switch.

Remember: the embed lives per theme. If the merchant publishes another theme later, the new theme starts without the embed. The per-theme table shows it: activate again on the new live theme.

Stage 3 · Verify

Goal: prove that the embed is running, not only enabled. "Enabled isn't running."

Do:

1. Open the storefront once, any page. This sends the beacon. If the store has a password page, enter the password.
2. Look at the storefront: the Ship to selector appears in the corner the merchant chose, and the old currency pickers are hidden.
3. Go back to the app, click Re-scan store and read 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.

Stop if: you see "No recent beacon from the storefront" after visiting the storefront. Go to the troubleshooting table (section 5).

Stage 4 · Remove

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

Do:

1. Go to the section 4 · Remove.
2. Click Queue script tag removal. The button works only when the store is verified and has script tags. If the store is not verified you see "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 tries again (see the table below).
5. Read the Theme cleanup checklist. Each line says the file, the line, what it is, and either "Already neutralized by the embed on the storefront." or "Not neutralized yet: activate the embed first."
6. Send Template B (section 4) to ask for written approval. Clean only on a duplicated, unpublished theme, then the merchant publishes it.

Don't: try to remove anything before the three signals are green. The app refuses it: "The embed is not verified on the live theme yet."

After March 1, 2027, script tags that are left will have no effect. Delete them anyway when you can: they still count as usage.

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 United States, Mexico…). Under Markets, that old variant is converted again, so the buyer sees a wrong price.

Do:

1. Go to 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 see "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 …" with its log.

You should see: the Audit column shows "✓ fixed price applied" for every row, and the last log line says the audit matches, for example 1/1 match.

Example from the development store: The Videographer Snowboard in Mexico went from 16,558.00 MXN (885.95 USD converted) to a fixed 15,999.00 MXN. The old "Mexico" variant alone would show 299,006 MXN, because Markets converts the old local price again.

Safe to repeat: the button changes to Run the … migration again. It reuses the catalog and the price list.

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.

Limits: charging in the local currency needs Shopify Payments or Adyen. Rounding works only with Shopify Payments.

Tokens · January 1, 2027

The card Tokens · January 1, 2027 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. This is an app-level change: escalate (section 7).

Report

In the section Report, click Download JSON and Download CSV. The files are named migration-<store>.json and migration-<store>.csv. See section 9.

4. Messages to the merchant

Replace the text in [brackets]. Keep the messages short.

Template A · Ask for the activation click

Subject: One click to keep your currency selector working after March 1, 2027

Hi [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] 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: [link from "Activate embed"]
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]

Template B · Ask for approval to clean the theme

Subject: Approval to remove old currency code from your theme

Hi [name],

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

[paste the "Theme cleanup checklist": file, line, what it is]

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]

5. Troubleshooting

6. What the kit can't do

Say these limits early, to the merchant and to your team:

• 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 the 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.

The app shows the same list in the column What this kit can't do.

7. When to escalate to the lead developer

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

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 the <html> tag in the storefront has no data-emk="running" (developer tools → Elements).
3. The embed state is Unreadable.
4. The token card is red: "Non-expiring offline token".
5. A queue job is failed, or a 401/403 token rejected comes back after the merchant re-authenticated.
6. "Migration for … stopped" shows an error you can't match with section 5.
7. The theme cleanup needs more than removing the lines in the checklist (custom code around them).

When you escalate, attach the store's JSON report and a screenshot of the section that shows the problem.

8. Per-store checklist

Print one per store.

• Collaborator access works, and the app is installed.
• Scopes approved (write_script_tags kept).
• Stage 1: numbers and markers written down. Live proof refused (optional).
• Stage 2: embed Enabled on the Live theme (merchant clicked Save).
• Stage 3: storefront visited, Ship to visible (two or more markets), status Active or Removed.
• Stage 4: queue done for every tag, or the tag is on the unreachable list with its cause.
• Stage 4: cleanup checklist sent; written approval received; clean copy published by the merchant.
• Stage 5 (if one variant per country): audit ✓ for every row; merchant told what is left for them.
• Tokens card green.
• JSON and CSV downloaded and added to the migration board.

9. The report and the migration board

Each store gives one report. Merge the CSV files of all stores into one sheet: that is the migration board.

The CSV has one row per finding, with these columns:

Useful views on the board:

• Filter section = verdict to see the status of every store in one column.
• Count section = script_tag per store to see what is left to delete.
• Group the unreachable stores (from the queue notes) into three buckets: frozen (402), locked (423, temporary) and closed (404). Deleting is not the bottleneck: the state of the stores is.

The JSON file has the full report: script tags, each theme with its embed state, markers and last beacon, the verdict, the token and the queue.