Migrating Checkout UI Extensions to Polaris Web Components: A Developer Checklist
A developer checklist for migrating Shopify checkout and customer account UI extensions to Polaris web components: audit, upgrade, test, deploy and fix issues.
From October 1, 2026, apps whose checkout or customer-account UI extensions still use API version 2025-07 or earlier can no longer be updated. Version 2025-07 was the last to support the React-based components, and versions from 2025-10 onward use Polaris web components. Shopify gave developers three extra months beyond the usual support window because of the size of the change, and its AI Toolkit can now help with the upgrade. That date has passed, so if your extensions are still on the old approach, treat this as an urgent fix. This checklist covers the steps. Always confirm details in Shopify’s developer documentation and changelog.
Why this change happened
Shopify has been unifying its interface components around Polaris web components across extension surfaces. The aim is consistent look and behaviour, better performance and an easier developer experience.
Before you start
- Inventory your extensions. List every checkout, thank-you, order status and customer-account extension you maintain.
- Record their purpose. Know what each one does and why it exists.
- Check dependencies. Note third-party libraries and API versions.
- Back up. Keep your repository clean, and branch before changes.
- Update tooling. Shopify CLI 4.0, released in May 2026, adds semantic versioning and auto-updates. Use a current version.
The migration checklist
- Read the migration guides. Shopify published component-by-component guides for checkout and customer-account UI extensions in May 2026.
- Upgrade the API version in your extension configuration to 2025-10 or later. Many developers go straight to 2026-01 or newer.
- Replace old components with Polaris web components. Use the Shopify AI Toolkit where it helps, then review everything it changes.
- Handle deprecated features. Shopify deprecated checkout metafields in checkout and customer-account UI extensions as of API version 2026-04. Move that data to cart metafields in checkout, or order metafields in customer accounts, and read it through
shopify.appMetafields. - Check event handling and state. Make sure inputs, validation and updates still behave.
- Review styling. Web components may render differently. Check spacing and responsiveness.
- Test on a development store. Use realistic carts, discounts and payment methods. Cover mobile.
- Test accessibility. Check labels, keyboard navigation and screen reader behaviour.
- Deploy with a version. Release in a quiet period and monitor.
- Document the changes so the next developer knows what was done.
Common problems to expect
- Components with no one-to-one replacement
- Styling differences
- Metafield-related logic that no longer works
- Extensions that depend on older API behaviour
After deployment
- Watch checkout completion rates and error logs.
- Ask support to flag any customer reports.
- Keep an eye on Shopify’s changelog for more deprecations.
Tips for agencies
Group clients by extension type, and migrate shared code once. Build a regression test list of carts and customer scenarios to reuse.
FAQ
What if I miss the deadline? Your app cannot be updated while any of its checkout or customer-account UI extensions use API version 2025-07 or earlier. Migrate those extensions to 2025-10 or later to ship updates again.
Can I automate this? Shopify’s AI Toolkit can upgrade extensions to new API versions, including the move to Polaris web components. Review its output carefully.
Related reading: How to Edit llms.txt and agents.md in a Shopify Theme, Shopify Theme Blocks and Nested Blocks: How to Build Flexible Sections and Shopify Metaobjects: Practical Use Cases for Custom Content and Logic.
Need help migrating?
Liquid Gold builds and migrates Shopify custom apps and checkout extensions. Talk about a custom app →