Shopify Checkout UI Extensions migration guide

Why this migration matters now

Many developers still talk about this change as if Shopify is simply asking them to move from legacy checkout code to Checkout UI Extensions. That framing is too narrow. The real transition is to checkout extensibility, which changes how checkout UI, business logic, post-purchase customization, and tracking are implemented across different surfaces.

In practice, that means older customizations built with checkout.liquid, Shopify Scripts, additional scripts, or script tags now need to be split apart and rebuilt with the right tool for each job. A shipping message inside checkout is not the same migration problem as a discount rule, and neither of those is the same as a Thank you page analytics snippet.

“Checkout UI extensions let app developers build custom functionality that merchants can install at defined points in the checkout flow.”

What Shopify is phasing out

The old checkout stack has not been retired all at once, but the direction is clear. Shopify’s current docs say checkout.liquid is already unsupported for the Information, Shipping, and Payment steps. On the Thank you and Order status pages, checkout.liquid, additional scripts, and script tags have been deprecated and moved onto separate sunset timelines depending on plan and surface.

The main legacy pieces developers still encounter are:

• checkout.liquid for checkout-step or post-purchase customization on older Plus implementations

• Shopify Scripts for discount, shipping, or payment logic

• additional scripts on the Thank you and Order status pages

• script tags used by apps for tracking or page customizations on legacy post-purchase pages

This is why developers should stop asking one broad question like “how do I migrate to Checkout UI Extensions?” and start asking narrower ones like “what replaces this exact customization on this exact surface?”

The transition is bigger than Checkout UI alone

The name that gets the most attention is Checkout UI Extensions, but that is only one piece of the replacement stack. A full migration may involve several technologies, depending on what the legacy implementation actually does.

A useful mental model is:

• Checkout UI Extensions for structured UI inside supported checkout targets

• Shopify Functions for server-side discount, shipping, payment, or validation logic

• blocks in the checkout and accounts editor for Thank you and Order status page content on the new pages

• web pixels or app pixels for tracking and event handling

That broader framing matters because teams often waste time trying to force one replacement technology to do everything. If a legacy script changed how payment methods behave, the answer is usually not “add a checkout banner.” If a legacy Thank you page snippet handled tracking, the answer is usually not “build a checkout step extension.”

For the two migration paths developers confuse most often, see the

for business-logic replacement and the

for bundle and cart-line structure work.

What each replacement technology is for

Shopify’s current platform guidance points developers toward a stack with clearer boundaries than the legacy model had. The useful question is not which API is newer, but which one owns the job you are trying to perform.

In most migrations, the split looks like this:

• Checkout UI Extensions for content or interaction inside checkout, such as messaging, field collection, order-summary UI, and supported extension targets

• Shopify Functions for things like discount logic, shipping method customization, payment method customization, and checkout validation

• blocks for recreating Thank you and Order status page customizations on the new pages

• web pixels or app pixels for tracking customer events after the move away from legacy scripts

It is also important to know what is not a replacement. Theme app extensions are for theme surfaces, not the checkout steps. Shopify’s theme app extension docs explicitly say app blocks and app embed blocks cannot be rendered on checkout step pages.

“Shopify Scripts will continue to work alongside Shopify Extensions in Checkout until June 30, 2026.”

That extension window is helpful, but it should be treated as migration time, not as a reason to postpone design decisions.

The dates that actually matter

This topic is full of half-remembered deadlines, so it is worth separating the important ones.

• checkout.liquid on checkout steps is already unsupported for the Information, Shipping, and Payment steps.

• Plus Thank you and Order status pages hit the August 28, 2025 deadline for upgrading away from legacy checkout.liquid, additional scripts, and apps using script tags on those pages.

• Automatic Plus upgrades began in January 2026 for stores still on the legacy Thank you and Order status pages, based on Shopify’s upgrade guidance.

• Non-Plus Thank you and Order status pages have until August 26, 2026 to upgrade to the new pages.

• Shopify Scripts continue to work only until June 30, 2026, after which they stop functioning.

There is one more developer-facing date worth knowing. Shopify’s script tag blocking docs say apps have not been able to create new ScriptTags on merchants’ Thank you or Order status pages since February 1, 2025. Older ScriptTags can persist for a time, but new legacy installs are already blocked.

How to audit an existing checkout customization

The cleanest migrations begin with an inventory. Shopify’s current upgrade guidance says a personalized upgrade guide is available in the Shopify admin for stores using the legacy Thank you and Order status pages. That report is useful, but developers should still do their own classification pass.

For each existing customization, capture:

• where it runs today
• what user-facing behavior it creates
• whether it is UI, business logic, or tracking
• whether it is merchant-configurable or hardcoded
• what data it needs
• what breaks if it disappears
• which deadline applies to it

In practical terms, that means a spreadsheet or issue list that treats every legacy customization as a discrete migration item. “Checkout customization” is too broad to estimate accurately. “Hide payment method X when order total is below threshold” is specific enough to map to a Function and test properly.

A practical migration map

Once the audit is done, the migration path usually becomes more obvious.

A reasonable mapping model looks like this:

• Legacy checkout-step message or input - move to a Checkout UI Extension if the target surface supports it

• Legacy discount, shipping, or payment logic - move to Shopify Functions

• Legacy Thank you or Order status page content - rebuild with blocks on the new pages

• Legacy analytics or marketing script - evaluate web pixels or app pixels

• Legacy DOM hacks - redesign the behavior around supported extension points or remove it

This is also the point where you decide what should not be migrated at all. Some old checkout customizations existed only because the platform used to be more permissive. If a customization creates marginal value and has no clean supported replacement, it may be better to delete it than to spend time forcing a weak recreation.

Common migration traps

Most painful migrations are not caused by syntax. They are caused by wrong assumptions about parity.

The most common traps are:

• assuming Checkout UI Extensions can replace every legacy behavior on their own

• trying to keep legacy tracking patterns instead of moving to pixels

• rebuilding unsupported DOM manipulation rather than redesigning the experience

• forgetting that checkout-step UI extensions are Plus-only

• treating Thank you page migration as “just analytics” when the page also contains business-critical content or support messaging

• waiting too long to test replacement behavior on real checkout configurations

Another common mistake is reaching for theme infrastructure out of habit. Theme app extensions and theme app embeds are useful, but they do not render on checkout step pages. If a team confuses theme surfaces with checkout surfaces, the migration plan will drift quickly.

What developers cannot do anymore

The migration gets easier once teams accept that some old patterns are gone. Legacy checkout customization often depended on direct code injection and broad page control. The newer model is more structured and more constrained.

In practice, developers should stop planning around:

• arbitrary DOM manipulation across checkout surfaces
• relying on new ScriptTags for legacy Thank you or Order status page behavior
• treating additional scripts as the future path for tracking or page logic
• assuming every legacy checkout.liquid behavior has a 1:1 replacement

This is not only a technical limitation. It is also a design constraint. Modern checkout extensibility is based on supported targets, defined APIs, and explicit capabilities. Migration work goes faster when developers design within those boundaries instead of fighting them.

Recommended migration sequence

If a store or app still has multiple legacy checkout dependencies, the safest sequence is usually:

1. inventory every legacy customization and assign the relevant deadline
2. replace business logic dependencies with Shopify Functions first
3. replace critical Thank you and Order status tracking with pixels
4. rebuild post-purchase content with blocks on the new pages
5. rebuild checkout-step UI with Checkout UI Extensions where supported
6. cut dead customizations instead of recreating low-value hacks
7. test each replacement on the actual store plan and surface

That order is not universal, but it prevents one of the worst migration outcomes: spending weeks polishing UI while critical payment, shipping, or tracking logic is still running on borrowed time.

Best internal links

These are the strongest next clicks after a checkout extensibility audit, because they map the most common adjacent migration work: Functions, bundle logic, app sprawl, and event validation.

• Shopify Scripts to Shopify Functions migration guide

  for migrating legacy discount, shipping, payment, and validation logic that checkout UI extensions do not replace.

• Cart Transform Function deep dive

  for bundle expansion, merge logic, and pricing cases that belong in cart structure rather than checkout-step UI.

• Shopify analytics playbook for operators

  for validating events and reporting after replacing additional scripts with pixels or app pixels.

• Shopify app stack audit tool

  for finding overlapping checkout, pixel, and storefront app behavior before a migration creates duplicate logic.

• Shopify app evaluation framework

  for deciding when checkout behavior should stay app-based versus moving into a custom Functions or extension build.

Sources and further reading

• Shopify Dev, checkout.liquid

• Shopify Dev, Apps in checkout

• Shopify Dev, Checkout UI Extensions

• Shopify Dev, technologies for customizing Shopify checkout

• Shopify Dev, cart and checkout validation

• Shopify Dev, payment customizations with Shopify Functions

• Shopify Dev, discounts

• Shopify Help Center, upgrading and replacing your Thank you and Order status pages

• Shopify Help Center, Plus upgrade guide for Thank you and Order status pages

• Shopify Help Center, non-Plus upgrade guide for Thank you and Order status pages

• Shopify Dev, ScriptTag functionality changes for Thank you and Order status pages

• Shopify Help Center, pixels and customer events

• Shopify Dev, theme app extensions configuration