Service eligibility and regional restrictions
PuppyIP serves only compliant overseas businesses and their authorized personnel. Proxy services are not available in mainland China. The service may only be used for lawful business activities outside mainland China. Use of this service within mainland China is prohibited.
Hosting a proxy IP or server overseas does not change these restrictions. The service must not be provided to end users in mainland China through relaying, forwarding, sharing or resale. Before use, read the Terms of Service.
Key Takeaways
- The new mechanism addresses ambiguous failures where a refresh response is lost or not persisted. It does not replace correct token-storage design.
- The old refresh token can be retried until the replacement refresh token is first used, with recovery capped at 30 days from the old token’s first use.
- The 30-day recovery period does not extend the normal 90-day refresh-token lifetime. Once the replacement is used, the old token retires.
- Serialize refreshes per shop and atomically save the access token and refresh token as a pair. Background tasks must read only the latest pair.
- 401 invalid_request signals that retries should stop and reauthentication is needed. Network errors, timeouts, 429s and transient 5xx errors qualify for bounded retries.
Why do all tasks return 401 after a successful refresh?
A typical sequence is an order or product synchronization worker noticing an expiring access token and successfully refreshing it with Shopify, followed by an interrupted return path, process exit or database transaction that saves only the access token and omits the new refresh token. Logs may show only a timeout or 5xx. The next task still uses the old token and eventually receives 401 invalid_request. The cost is not one failed request: an entire shop’s background synchronization can stop, queues repeatedly retry and merchants must reopen the app.
The most dangerous instincts are launching multiple refresh requests at once or retrying indefinitely on 401. First pause queue consumption for that shop and preserve status code, request ID, refresh start time and current token-record version. Establish whether any worker has already used the replacement refresh token before deciding whether the old token remains recoverable.
Old and new rules: the fixed 60-minute window is no longer the criterion
Previously, an already-used refresh token could be retried for up to 60 minutes. If the app failed to receive or store the returned access and refresh tokens, the old token became unusable after that window, often leaving reauthentication when the merchant reopened the app as the only option.
From August 28, 2026, apps using expiring offline access tokens can keep retrying the previously stored refresh token until they start using its replacement. Recovery is capped at 30 days after the old refresh token’s first use and does not extend its normal 90-day lifetime. Once the replacement is used, the preceding token retires immediately. No new API version, configuration or opt-in is required.
Establish whether you are in scope
This page applies to apps calling the Admin GraphQL API or Admin REST API with expiring offline access tokens, especially public apps running webhooks, order synchronization or scheduled tasks without an active merchant session. Official Shopify app templates generally handle refresh, but custom authentication layers, queues and databases must still guarantee storage consistency.
Apps not using expiring offline access tokens are unaffected by this recovery mechanism. Custom or merchant-created apps should also not apply the 2027 public-app mandatory migration rule to themselves. If the issue concerns online tokens, client credentials, permission scopes, uninstallations or client-secret revocation, use the corresponding authentication flow rather than this recovery path.
Seven checks for per-shop recovery
First, pause refresh and dependent tasks for the shop to avoid concurrent consumption of one token. Second, read the current token pair, record version, first-refresh time and expiry fields without hardcoding durations. Third, inspect logs for any request already made with the replacement refresh token. Fourth, for only a timeout, network error or transient 5xx, make one controlled retry with the old refresh token still stored in the database. Fifth, save the returned access token, refresh token, expires_in and refresh_token_expires_in in one database transaction. Sixth, use compare-and-swap or a row lock to reject stale workers overwriting newer versions. Seventh, resume the shop’s queue only after commit and validate with one read-only Admin API request.
The refresh endpoint’s success response is not completion; atomic persistence of the token pair is. Keep a token generation or version per shop and make workers read from one authoritative record. Log only hashes, the last four characters or versions, never complete tokens.
Status-code decisions: retry or stop
Network connection errors, client timeouts, 429s and transient 5xx responses may enter bounded retries with jitter, continuing to use the same refresh token for the ambiguous failure. For 401 Unauthorized with invalid_request, Shopify groups terminal conditions such as unknown or expired tokens, replay outside the recovery window, app uninstallations and revocations under the same error. Stop automatic retries and mark the shop for reauthentication.
Do not classify every 403 as a network or refresh-token error either. After January 1, 2027, public apps calling Admin API with non-expiring offline tokens receive a 403 containing a migration notice; missing scopes can also cause 403. Match the official error message and check token type and scopes before choosing token exchange, reauthorization or a permissions fix.
Validate with fault injection before launch, not experimentation on merchant stores
In development stores, simulate four cases separately: client timeout after successful refresh, transaction rollback after a successful response, two workers refreshing concurrently, and reuse of an old token after the replacement has been used. The first two should recover with exactly one final token pair, the third should be blocked by a serialization lock or version check, and the fourth should stop retries and enter reauthentication.
Roll out to a small number of shops first, monitoring refresh success with persistence failure, same-shop concurrency conflicts, 401 invalid_request, reauthentication counts and queue backlog. Stop expansion if any rises unexpectedly. Rolling back application code must not roll back the new database token pair, or a still-valid replacement will be lost.
Common misconceptions and network boundaries
The first mistake is treating 30 days as the new refresh-token lifetime; the normal lifetime remains 90 days, with recovery only a capped period within it. The second is assuming old and replacement tokens can coexist indefinitely; the old token retires on first use of the replacement. The third is each worker caching its own token, repeatedly resurrecting retired versions. The fourth is changing egress IP on 401; a terminal authentication state does not recover through a new network.
Only with DNS, TLS, connection timeout or explicit transient 5xx evidence should you first consult the proxy connection troubleshooting checklist for transport issues. For stable cross-border store background tasks, visit the PuppyIP website to learn about network environments. A network can reduce lost responses, but cannot replace serialized refresh, atomic persistence and correct reauthentication.
Sources
Frequently Asked Questions
When was this Shopify refresh-token change announced?
The Shopify Developer Changelog published it on August 28, 2026. It applies to apps using expiring offline access tokens without an API-version change, configuration or opt-in.
How long can the old refresh token be retried now?
Until the replacement refresh token is first used, capped at 30 days after the old token’s first use and never beyond that token’s normal 90-day lifetime.
Can we return to the old token after using the replacement?
No. Once the replacement refresh token is used, the preceding refresh token retires. Replaying it then is not lost-response recovery.
Should 401 invalid_request keep retrying?
Do not retry automatically without limit. Shopify groups terminal states such as expiry, revocation, uninstallation, unknown tokens and replay outside the recovery window under this error. Stop and have the merchant reauthenticate.
Why must both tokens be saved atomically?
The access token and refresh token form a pair returned by the same rotation. Saving only one makes later API calls and refreshes use credentials from different generations, causing difficult-to-recover 401s.
Can changing IPs solve refresh-token 401s?
No. 401 invalid_request concerns credential state. Investigate the network separately only with independent evidence such as timeouts, DNS, TLS or transient 5xx errors.