If your public app still holds a non-expiring offline access token, January 1, 2027 is the hard migration deadline. Miss it and your app gets delisted from the Shopify App Store the same day, with API calls starting to return HTTP 403 errors from April 1, 2027. The fix is a one-time server-side token exchange that requires zero merchant interaction.
Key takeaways
- All public apps (including those created before April 1, 2026) must switch to expiring offline access tokens by January 1, 2027.
- Expiring offline tokens have a 60-minute access-token lifetime and a 90-day refresh-token lifetime.
- The migration is a server-side token exchange POST, not a reinstall. Merchants never see it happen.
- The exchange is irreversible per shop: once you trade the old token, the original is immediately revoked.
- Custom apps, merchant-created apps, and online access tokens are not affected by this change.
Background: how we got here
Shopify shipped expiring offline token support in late 2025. On April 1, 2026, expiring tokens became mandatory for all newly created public apps. Then on May 20, 2026, Shopify extended the same requirement to every existing public app, setting January 1, 2027 as the deadline.
The motivation is straightforward: a credential that never expires is a credential that never gets rotated. A leaked non-expiring token stays useful indefinitely. The new model gives each access token a 60-minute window and a 90-day refresh token that rotates on every use.
I maintain a handful of public apps across the stores I work on. The token migration itself is maybe two hours of work per app. The part that takes longer is making sure the refresh loop is correct and that failed refreshes are handled without silently killing background jobs.
The enforcement timeline (updated October 27, 2026)
Shopify clarified the enforcement schedule in their October 2026 security update. The phased rollout is designed to give merchants time to prepare, but Shopify is explicit: January 1 is the migration deadline, not a grace period.
| Date | What happens |
|---|---|
| April 1, 2026 | Expiring tokens required for all newly created public apps |
| January 1, 2027 | Unmigrated apps delisted from App Store, blocked from new installs; existing installs still work |
| January 15, 2027 | Merchants using unmigrated apps see a warning in Shopify admin |
| April 1, 2027 | Admin API requests using non-expiring offline tokens return HTTP 403 |
One point that trips people up: there is a discrepancy in Shopify's own docs. The migration guide has at times stated a 403 kicks in on January 1, while the October 27 changelog sets April 1 for existing installs. Treat January 1 as your real deadline regardless, because delisting happens that day and merchant-visible warnings follow two weeks later.
Who is and is not affected
Affected:
- Public apps (App Store listed or unlisted) calling the Shopify Admin API with non-expiring offline tokens
- Apps created before April 1, 2026 that were previously exempt
Not affected:
- Custom apps (created in the Partners Dashboard for a specific store)
- Merchant-created apps
- Online access tokens (these already had per-session expiry)
If your stored tokens have never changed since the initial OAuth install, you are running non-expiring tokens and need to act now.
Quick audit: open your app's Logs in the Partners Dev Dashboard, filter Type to "GraphQL request", then filter Token type to "Offline, non-expiring". If you see hits there, the migration is not done.
How expiring offline tokens work mechanically
The access-token lifetime is 60 minutes. The refresh token that comes with it is valid for 90 days. When you use a refresh token to get a new access token, Shopify rotates both: you receive a new access token and a new refresh token (resetting the 90-day clock). The previous access token stays valid until its own 60-minute expiry elapses, so in-flight requests complete cleanly.
Critically: only one expiring offline token can be active per app-and-store combination. Minting a new one retires all previous ones. This matters for your refresh locking strategy (covered below).
Migration path options
Option 1: Gradual (new installs only)
Add expiring=1 to the token request your app already makes during OAuth install. New installs get expiring tokens; existing installs remain on the old token until they reinstall or you proactively exchange them.
This is insufficient on its own if you have shops that run background jobs and may never open the app before January 2027.
Option 2: Proactive batch exchange (all existing installs)
Use the token exchange grant to trade every stored non-expiring token for an expiring pair, with no merchant interaction required. This is what most apps with background sync jobs need.
| Approach | Merchant interaction required | Covers existing installs | Recommended for |
|---|---|---|---|
Add expiring=1 to new installs only | None | No | Apps where merchants reinstall frequently |
| Proactive token exchange batch job | None | Yes | Background sync, webhooks, scheduled jobs |
| Wait for merchant to open app | Re-auth prompt | Only after open | Interactive-only apps (not recommended) |
The exact migration steps
Step 1: Verify your current token state
Check your session storage. If your stored access tokens look like shpat_... and have never changed since install, you are on non-expiring tokens. Run the Dev Dashboard log filter described above to confirm.
Step 2: Update your OAuth install flow for new installs
If you use the @shopify/shopify-app-remix or @shopify/shopify-app-express template, enable expiringOfflineAccessTokens: true in your shopifyApp() config and redeploy. The template handles storage and refresh automatically.
If you use the authorization code grant directly, add expiring=1 to the POST that exchanges the authorization code:
POST https://{shop}.myshopify.com/admin/oauth/access_token
client_id={api_key}
client_secret={api_secret}
code={authorization_code}
expiring=1
If you use token exchange (App Bridge session tokens), add expiring=1 to your exchange request:
POST https://{shop}.myshopify.com/admin/oauth/access_token
client_id={api_key}
client_secret={api_secret}
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token={session_token}
subject_token_type=urn:ietf:params:oauth:token-type:id_token
requested_token_type=urn:shopify:params:oauth:token-type:offline-access-token
expiring=1
Important: without expiring=1, the token exchange endpoint returns the legacy non-expiring shape even if you think you have opted in. This is a known footgun reported in the developer forums.
Step 3: Persist both tokens atomically
The response now contains both access_token (60-minute TTL) and refresh_token (90-day TTL), plus expires_in and refresh_token_expires_in. Store both in a single atomic write. If you write them in two separate operations and your process crashes between them, you will have a mismatched state.
{
"access_token": "shpua_...",
"expires_in": 3599,
"refresh_token": "shprt_...",
"refresh_token_expires_in": 7775999
}
Note: newer access tokens may be prefixed shpua_ rather than the shpat_ prefix common in older Shopify examples. Update any prefix-based validation logic.
Step 4: Migrate existing installs via token exchange
This is the critical batch job. For each shop in your session storage that still holds a non-expiring token:
POST https://{shop}.myshopify.com/admin/oauth/access_token
client_id={api_key}
client_secret={api_secret}
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token={existing_non_expiring_token}
subject_token_type=urn:shopify:params:oauth:token-type:offline-access-token
requested_token_type=urn:shopify:params:oauth:token-type:offline-access-token
expiring=1
Both requested_token_type and expiring=1 are required. Shopify rejects online tokens, delegate tokens, scope-restricted tokens, and tokens that already expire as the subject_token.
This exchange is irreversible. Once successful, the old non-expiring token is revoked immediately. If you fail to persist the new token pair before your process terminates, that shop will need to reinstall the app. Run this under a database transaction or write-then-confirm pattern.
If you are using the @shopify/shopify-api Node library, the helper method is:
const response = await shopify.auth.migrateToExpiringToken({
session: existingSession,
});
// Save response.session immediately
await sessionStorage.storeSession(response.session);
Step 5: Implement the refresh loop with proper locking
The standard pattern is to refresh proactively, before the 60-minute window closes, rather than on a 401. Refreshing on a 401 causes a request to fail visibly; proactive refresh keeps things clean.
Key rules:
- Use a per-shop distributed lock before refreshing. Only one process should hold the refresh token for a given shop at a time. Because minting a new expiring token retires the old one, concurrent refresh calls will orphan one another.
- Store the new access token and new refresh token atomically in the same transaction on every rotation.
- Handle non-transient failures separately. A 401 on refresh can mean an uninstalled app, a closed shop, or a revoked grant. These are not retryable. Log them, mark the session as invalid, and stop calling the API for that shop.
async function getValidToken(shop: string): Promise<string> {
const session = await sessionStorage.loadSession(shop);
const bufferSeconds = 120; // refresh 2 min before expiry
if (session.expiresAt - Date.now() / 1000 < bufferSeconds) {
// Acquire per-shop lock here (Redis SETNX or equivalent)
const refreshed = await shopify.session.refreshToken(session);
await sessionStorage.storeSession(refreshed); // atomic
return refreshed.accessToken;
}
return session.accessToken;
}
Step 6: Verify migration is complete
- Return to the Dev Dashboard Logs view and re-run the "Offline, non-expiring" token filter. The count should drop to zero as you process the batch.
- Watch for
refresh_token_expires_inin your stored sessions. If it is missing, the token is not expiring. - Monitor for HTTP 401 responses in your API client after the batch job. A fresh 401 immediately after a successful exchange indicates a locking or storage race.
What custom apps need to do (spoiler: nothing)
This change applies only to public apps. Custom apps and merchant-created apps are outside scope. If you are building a bespoke integration for a single merchant and distributing it as a custom app through the Partners Dashboard, you are not affected by this deadline.
See the glossary entry for access token types for a quick reference on how offline, online, and delegate tokens differ.
Common mistakes to avoid
- Forgetting
expiring=1on the token exchange call. Without it, the response looks valid but you get a non-expiring token and nothing has changed. - Not locking the refresh call per shop. Two concurrent webhook handlers for the same shop will both try to refresh, the second one invalidates the first's new token before it is used, and you end up with a cascade of 401s.
- Treating April 1, 2027 as the real deadline. Your app gets delisted and merchants see warnings well before that. Plan for January 1.
- Not covering shops that never open the app. Background-only integrations (3 AM inventory syncs, for example) will never trigger an install-time token refresh. Those shops need the proactive batch exchange.
- Skipping the
refresh_token_expires_incheck. If your batch job runs but the new sessions are missing this field, something went wrong silently.
Conclusion
The migration is not architecturally complex, but it is easy to do partially and think you are done. The three things that actually require care are: atomic token storage, per-shop refresh locking, and covering every existing install including shops that run only in the background. Run the Dev Dashboard log filter before and after the batch job to confirm the "Offline, non-expiring" count reaches zero. With eight weeks left before the January 1 delisting date, there is still time to do this properly rather than urgently.
If you would rather hand this off, my studio Lintel offers custom Shopify app development.
Frequently asked questions
What exactly breaks on January 1, 2027 for unmigrated apps?
Apps that have not migrated to expiring offline access tokens will be delisted from the Shopify App Store and blocked from new installs on January 1, 2027. Existing installs continue to work temporarily, but merchants see warning messages in their Shopify admin from January 15, and Admin API calls using non-expiring tokens return HTTP 403 from April 1, 2027.
Does a merchant need to reinstall my app for the migration to work?
No. The token exchange grant lets you trade each stored non-expiring token for an expiring pair entirely on the server side. No merchant interaction is required. The only time a reinstall becomes necessary is if the exchange succeeds but you fail to persist the new tokens before your process terminates.
Are custom apps and merchant-created apps affected by the January 2027 deadline?
No. This change applies only to public apps, whether listed on the Shopify App Store or distributed as unlisted public apps. Custom apps, merchant-created apps, and online access tokens are explicitly outside the scope of this requirement.