Migrating Complex Portals from Shopify Legacy Customer Accounts

The migration is a system replacement, not a settings toggle

The safe answer is simple: do not upgrade a complex legacy account portal until every customer-facing capability has a named replacement, an owner, an acceptance test, and a rollback step. The account-version switch is the last action in the migration, not the first.

Shopify deprecated legacy customer accounts on February 26, 2026. The official changelog says they are no longer available to new stores or existing stores that were not already using them, and that a final sunset date will be announced later in 2026. As of August 1, 2026, that final date had not been published. Do not turn “later in 2026” into a made-up deadline for a project plan.

Read Shopify's February 26, 2026 deprecation notice.

The easy migrations are stores that use the standard login, order history, profile, and address pages. The risky migrations are portals that quietly turned account templates into an application shell: password SSO through Multipass, loyalty balances, B2B company context, invoices from an ERP, subscription management, returns, support tickets, gated downloads, or a headless frontend sharing identity with Shopify.

Those capabilities do not move together. Shopify's current account product is passwordless, hosted separately from the theme, and customized through native features, apps, UI extensions, and the Customer Account API. Legacy Liquid and JavaScript are not carried into that runtime.

Shopify automatically redirects standard legacy account URLs such as /account/login after the upgrade. That is useful route continuity, not feature parity. Custom login modals, separate registration pages, hard-coded app callbacks, email links, and external portal bookmarks still need to be found and tested.

Theme deployment is also part of the cutover boundary. Shopify's developer notice warns that installing a theme without the legacy customer-account Liquid files automatically upgrades a store that is still using legacy accounts. Do not let an unrelated theme release perform the identity migration before the portal is ready.

Read Shopify's developer-facing deprecation and theme-install warning.

Start with a feature and dependency inventory

Start from customer jobs, not files. A list of templates under templates/customers tells you where some legacy UI lived; it does not tell you which support workflow, external system, or commercial promise depends on it.

Build one ledger with a row for every task a customer, support agent, or automation performs. Include the current entry point, identity assumption, source of truth, write side effects, replacement owner, test evidence, and rollback action.

Shopify's upgrade guide explicitly asks merchants to inspect the seven legacy customer templates and their Liquid customizations. Do that code inventory, then search beyond it: routes, menu URLs, email templates, app settings, proxy endpoints, customer tags, Flow workflows, segment queries, webhook handlers, and support documentation.

Two legacy assumptions deserve their own rows. Shopify says the Flow customer account enabled and customer account disabled triggers are not supported for customer accounts. It also says segments based on customer_account_status do not represent sign-in activity in customer accounts. Replace the business requirement, not just the syntax. “Send a welcome message after first order” may be possible; “detect the first password-based activation” no longer describes the new identity model.

Check Shopify's current customization and unsupported-feature matrix.

Choose a replacement surface for every capability

A complex portal becomes manageable when every row has one primary presentation surface and one source of truth. “We can rebuild it with an app” is not a decision. Name the target, data boundary, merchant control, and failure behavior.

Shopify's current extension model supports blocks, static targets, and full pages. A full-page extension gets a dedicated route and can be added to the customer account menu. Extensions run in an isolated runtime and use platform components and APIs; they are not theme iframes with a nicer name. Protected customer data access and network access still need the appropriate app approval and configuration.

Review the current customer account UI extension targets and capabilities.

Use the smallest surface that can own the workflow cleanly. A shipment-status badge belongs in an order block. A return wizard probably needs an order-specific full page. A multi-brand portal spanning commerce, warranty, training, and enterprise entitlements may justify a separate application using the Customer Account API and external services.

The decision should survive an app outage. Define what remains visible, which actions become unavailable, whether Shopify's native page still works, and how support can complete the task without inventing customer state.

Redesign identity, Multipass, and headless sign-in

Identity is the first hard boundary because the legacy and current account models are not equivalent. Customer accounts use email-based one-time codes by default; password activation and reset flows are no longer the organizing lifecycle.

Shopify documents Multipass as a legacy-customer-account feature. If an external site currently generates a Multipass token and redirects the customer into Shopify, there is no “enable Multipass for customer accounts” checkbox waiting at the end of the migration.

There are two supported directions to evaluate:

• Shopify-hosted accounts with a custom identity provider. Shopify documents an OpenID Connect integration for Shopify Plus. The provider authenticates the customer and returns an ID token; Shopify uses identity claims to create or resume the session.

• A bespoke headless account experience. The Customer Account API uses an OAuth 2.0 authorization-code flow. Shopify documents public, web, mobile, and confidential client types; a server-backed Rails portal belongs in the confidential-client category when it can protect the client secret and refresh token.

A custom identity provider is not a passive second login button. Shopify's current connection guide says only one custom provider can be active, activation signs existing customers out, and the merchant can switch back to Shopify's default provider. Treat discovery endpoints, redirect URIs, signing keys, claims, logout, refresh tokens, and the provider's own availability as production dependencies.

Read Shopify's current custom identity-provider requirements, including theconnection and rollback behavior, then compare them with theCustomer Account API authorization flow.

Do not confuse Customer Account API access tokens with Shopify app session tokens. The former authorize a customer-facing app to access that customer's account data. Session tokens let an extension authenticate a request to your app backend. Admin API credentials remain a separate server-side concern.

The identity acceptance matrix should cover more than a successful login:

• new and returning D2C customers;
• customers whose email casing or address changed;
• B2B contacts attached to one and multiple company locations;
• headless web and mobile callbacks, logout, refresh, and expired sessions;
• email-code delivery, sender address, social sign-in if enabled, and support recovery;
• cross-domain redirects, locale and market context, and a rejected or stale authorization response;
• credential rotation with old credentials retained until every client has moved.

If the business cannot name the identity authority for each entry point, the architecture is not ready. Running password, Multipass, one-time-code, and external-provider paths without a precise boundary creates duplicate support flows and makes “logged in” mean something different in every system.

Plan B2B and blended-store behavior

Shopify B2B is not a side case to test after D2C. Shopify says legacy customer accounts cannot be used for B2B customers and orders. In a blended store, changing the account version affects both audiences.

Shopify currently determines the signed-in experience from the email's relationship to customer and company-location records. An email associated with a company location enters the B2B experience; an email associated only with a customer enters D2C; an unmatched email can create a new D2C profile. That makes data preparation part of the release, not an admin tidy-up for later.

Verify Shopify's current B2B sign-in and blended-store behavior.

Test at least these B2B jobs with deliberately separate fixtures:

• a contact assigned to one company location and one catalog;
• a contact assigned to multiple locations with different permissions or commercial context;
• a D2C customer who shares the blended storefront but has no company assignment;
• order history, reorders, saved payment methods, payment actions, returns, and company details;
• account access requests and approval workflows that used to rely on registration or activation events;
• custom account extensions scoped to the intended markets and company locations.

Keep plan eligibility explicit. Shopify's custom identity-provider connection and Shopify B2B are Plus capabilities. A migration document that says “replace Multipass with OIDC” without checking the merchant's plan is an architecture diagram, not a viable plan.

For more detail on blended-store choices, use the

Shopify B2B on one store guide

as the commercial-model companion to this migration workflow.

Keep external portals and app data inside explicit boundaries

External systems are not a problem by themselves. The problem is an account page that reads one system, writes another, guesses that both succeeded, and gives support no way to reconcile them.

For every external capability, write down five things: source of truth, read path, write path, idempotency key, and recovery owner. A practical boundary map might look like this:

A Shopify-hosted extension can call your backend when network_access is configured, using a session token so the backend can verify the signed shop and customer context. Your backend must still authorize the specific action and resource. Do not send Admin API tokens, ERP secrets, or policy decisions into the extension.

Include metafield definitions in the inventory. Since June 16, 2026, Shopify requires a definition with customer-account permissions before the Customer Account API returns an app-owned metafield. A missing value can therefore mean “definition or access missing,” not simply “this customer has no data.” Record the definition owner, deployment order, and empty versus unauthorized behavior for every field used by the portal.

Verify Shopify's Customer Account API metafield-definition requirement.

The

Rails backend architecture guide

owns that system boundary. The

extension-to-Rails guide

owns request verification, CORS, endpoint design, and failure handling. This article owns the migration decision that determines which workflows need those implementation patterns.

Stage coexistence without splitting customer truth

Shopify provides a useful preparation path. You can duplicate a checkout and accounts configuration, add the replacement apps and branding, publish that configuration, and preview customer accounts through their direct URL while the storefront and checkout still link to legacy accounts. That creates a test window before the version switch.

It does not create a supported percentage rollout where 10% of real customers use one account model and 90% use the other. Treat the direct customer-account URL as a controlled validation surface for staff and test customers, not as permission to run two production identity truths.

Shopify separately supports rollouts for checkout and accounts configurations. The documented rollout scope does not say it splits the store's legacy-versus-current account version by cohort. That distinction is an inference from Shopify's documented scope, so keep the authentication cutover store-wide unless Shopify publishes a specific account-version rollout contract.

Compare Shopify's configuration Rollouts with the account-version upgrade.

A workable sequence is:

1. Freeze and inventory. Record current routes, templates, apps, identity, domains, workflows, segments, support macros, and external writes. Assign owners.

2. Build the replacement configuration. Duplicate the current configuration, apply shared checkout/account branding, add blocks and full-page extensions, and prepare the account subdomain.

3. Validate with synthetic accounts. Use the direct customer-account URL for D2C, B2B, multi-location, market, locale, mobile, and failure fixtures. Do not use customer data in screenshots or the repository.

4. Shadow external reads. Compare the new path with the current authoritative systems. Keep writes disabled or idempotent until the exact recovery contract is tested.

5. Prepare the cutover. Update custom modal code, nonstandard account links, emails, apps, DNS, support guidance, monitoring, feature flags, and on-call ownership.

6. Upgrade and stabilize. Switch the account version, confirm standard legacy URLs redirect, and observe sign-in, task completion, B2B context, downstream writes, and support failures through the documented reversion window.

Follow Shopify's current duplicate, publish, preview, and upgrade sequence.

Coexistence is safest when it is read-oriented. Dual-writing customer or portal state across old and new paths without idempotency and reconciliation creates the exact uncertainty the migration is meant to remove.

Build a rollback plan that covers more than the switch

Shopify's upgrade guide currently says merchants can revert within 30 days. Use that as one control, not as the whole rollback design. The Shopify setting cannot restore a deleted login modal, reverse a DNS change, recover revoked API credentials, unsend an email, or undo writes already accepted by an external platform.

Before cutover, capture and test rollback for:

• the active and replacement checkout/accounts configurations;
• the legacy theme version and every custom account entry point removed for launch;
• account-domain DNS, certificate readiness, TTL, and the previous records;
• identity-provider clients, redirect URIs, signing keys, and credential rotation order;
• feature flags for extension pages, backend writes, webhooks, jobs, and external callbacks;
• data produced during the new-account window and how legacy support can still see it;
• support scripts for failed sign-in, missing B2B context, missing account tasks, and manual completion.

Write objective rollback triggers. Examples include a sustained sign-in failure above the agreed threshold, customers landing in the wrong B2B/D2C context, an essential portal task lacking a working fallback, or downstream writes that cannot be reconciled. “The launch feels bad” is too vague; “company-location context is missing for two verified B2B fixtures” is actionable.

Reversion also needs a forward-fix decision. If the new account flow wrote a return request or changed a subscription, preserve that truth when the presentation layer rolls back. Never restore an old screen by erasing actions customers already completed.

Use a release gate, not a hopeful launch date

A release date answers when. A release gate answers whether the system is ready. Do not approve the upgrade until the following evidence exists for the store's actual capability set.

Identity and entry points

• Every account link, login modal, registration path, email link, and external callback has an expected destination.
• D2C, B2B, headless, and mobile sign-in/logout/session-expiry fixtures pass.
• The sender email, account subdomain, custom identity provider, and recovery process are verified where used.

Customer jobs

• Every inventory row is accepted, intentionally retired, or has a documented fallback.
• Order, profile, address, return, credit, subscription, invoice, loyalty, support, and download tasks are tested only when the store actually offers them.
• Desktop and mobile behavior, empty states, unavailable dependencies, and permission failures are captured without personal data.

Operations and recovery

• Unsupported legacy Flow triggers and account-status segments have replacement business rules or an explicit retirement decision.
• External writes are idempotent, observable, and reconcilable; read failures degrade honestly.
• A theme deployment cannot trigger an accidental early upgrade by omitting required legacy templates.
• Dashboards, alerts, support macros, owners, rollback triggers, and the first 30 days of review are scheduled.
• The team has rechecked the official deprecation notice and upgrade limitations within 48 hours of launch.

The result is not “feature parity at any cost.” Some legacy behavior should be retired because it encoded a password lifecycle, duplicated Shopify, or never produced enough value to justify rebuilding. The important thing is that retirement is an explicit product decision with customer communication, not a surprise discovered after the switch.

Best internal links

This guide owns migration discovery and rollout. Use these implementation guides once the replacement surface is chosen:

• Customer Account UI Extensions with a Rails backend

  for extension-versus-backend ownership.

• Calling a Rails API from a customer account extension

  for authenticated actions and external-system calls.

• Session tokens for Shopify UI extensions

  for the frontend-to-backend authentication boundary.

• Shopify B2B on one store

  for blended B2B/D2C operating decisions.

• Platform Engineering hub

  for the surrounding authentication, API, reliability, and app-architecture paths.

Sources and update triggers

Platform status and behavior were checked on August 1, 2026. Technical claims use official Shopify sources; community discussions can demonstrate migration pressure, but they do not define the platform contract.

• Legacy customer accounts deprecation notice — February 26, 2026
• Developer deprecation notice and theme-install warning
• Upgrading to customer accounts from legacy customer accounts
• Customization options for upgrading customer accounts
• Customer authentication and custom identity providers
• Customer Account API getting started
• Customer account UI extensions
• Checkout and accounts configuration Rollouts
• B2B sign-in and customer accounts

Review this article immediately when Shopify announces the final legacy-account sunset date, changes the 30-day reversion policy, expands identity-provider eligibility, changes Multipass availability, alters the Customer Account API authorization contract, changes extension-target availability, or changes B2B/blended-store account behavior. Otherwise, recheck it every 90 days while the deprecation is active.