Updated 6 Oct 2026: Shopify's September 29 update closes the previously documented lost-response failure trap for direct legacy-token migration: the original non-expiring token can now recover the same issued pair for up to seven days, with earlier stop conditions after refresh or later token acquisition.

Key details

  1. Shopify announced recoverable direct legacy-token migration on September 29, 2026.
  2. An eligible retry can use the same original non-expiring token and client credentials for up to seven days.
  3. The retry returns the same access-token and refresh-token pair issued by the original migration.
  4. Recovery stops once the issued pair has been refreshed or a later token acquisition retires it.
  5. If the original token is no longer eligible and Shopify returns invalid_subject_token, the app must acquire a new token through the normal authenticated flow.
  6. The August 28 recovery behavior for ordinary expiring-token refresh rotation remains separate.
  7. Public apps must use expiring offline tokens for GraphQL Admin API requests by January 1, 2027.

What builders should take away

  1. Treat direct legacy-token migration retries as recovery of one transaction, not permission to start parallel migration attempts.
  2. Persist access token, refresh token and expiry metadata atomically before marking a store migrated.
  3. Keep per-store token exchange and refresh operations serialized so a later acquisition does not unexpectedly invalidate a recovery attempt.
  4. On ambiguous migration timeouts, retry the same request with the original legacy token inside the recovery window before asking the merchant to reauthorize.
  5. Handle invalid_subject_token as a state transition requiring normal token acquisition rather than repeatedly replaying the migration.

What changed

On September 29, 2026, Shopify added lost-response recovery to the direct migration path from legacy non-expiring offline tokens to expiring offline access tokens. If the initial migration succeeds but the response is lost before the app persists the credentials, an eligible retry using the same original non-expiring token and client credentials can return the same access-token and refresh-token pair for up to seven days. Shopify's current migration guide now documents the same behavior. This closes the failure trap that remained after Shopify's August 28 improvement to ordinary refresh-token rotation, where the previously stored refresh token can be retried after a lost refresh response until the replacement begins being used, within that flow's own bounds.

Why it matters

The January 1, 2027 migration deadline still forces existing public apps off non-expiring offline tokens for GraphQL Admin API access, but unattended migration is no longer inherently unsafe to replay after an ambiguous timeout. That matters most for background workers, webhook consumers, app proxies and large installed bases where a merchant may not be present to repair a failed exchange. Builders still need durable token storage and per-store serialization because the migration retry is bounded: recovery can stop after the issued pair is refreshed or a later token acquisition retires it.

Direct legacy-token migration now has a replay window

When an app migrates a stored non-expiring offline token without a user session, Shopify now lets it repeat the same migration request with the original token and client credentials for up to seven days. Eligible retries return the same access-token and refresh-token pair rather than creating a second credential chain.

Recovery can end before seven days

The seven-day window is a maximum, not an unconditional guarantee. Shopify says recovery stops after the app refreshes the issued pair or a later token acquisition for the same store retires it. If the retry then returns invalid_subject_token, the app must obtain a new token through the normal authenticated flow.

Ordinary refresh rotation keeps its separate recovery semantics

Apps already using expiring offline tokens can still recover a lost refresh response by retrying the previously stored refresh token until its replacement is used, subject to Shopify's refresh recovery and token-lifetime rules. The September change brings the one-time legacy migration much closer to that operational safety model without making the two flows identical.

The January 2027 deadline is unchanged

Existing public apps must use expiring offline tokens for GraphQL Admin API requests by January 1, 2027. Shopify's migration guide still supports both normal user-driven acquisition and direct background migration for inactive or background-only installations.

Durable storage still matters

A replay window reduces the cost of a lost HTTP response but does not eliminate credential-state bugs. Apps should serialize token operations per store, atomically persist returned pairs and expiry values, and record migration state so ambiguous failures are retried deliberately rather than treated as fresh migrations.

What to watch next

  • Any change to the January 1, 2027 enforcement timetable.
  • Whether Shopify exposes migration-state or bulk-progress APIs for large installed bases.
  • Operational evidence on how the seven-day recovery behaves under concurrent refresh or token-acquisition races.
  • Further framework support that makes direct migration and durable token replacement automatic.

Still unclear

  • The seven-day recovery window can terminate earlier after the issued pair is refreshed or another token acquisition supersedes it.
  • Apps using Shopify-managed framework authentication may have different operational steps than integrations implementing token exchange directly.
  • The change reduces lost-response risk but does not protect against lost local credentials after the recovery conditions expire.

Sources

Direct reading behind this dossier.

4 sources
Access tokens
Shopify primary_documentation

Current token model and public-app requirement for expiring offline access tokens.

Discussion

Discussion is reader-contributed. Comments are not part of the BTN dossier or its editorial evidence.

0 visible comments

Join the discussion

Keep comments useful and relevant. Reader contributions may be moderated and are not BTN editorial evidence.

Sign in to comment