# Shopify Expiring Offline Access Tokens: Migrate Before 2027

Source: https://bealinawaz.com/blog/shopify-expiring-offline-access-tokens/
By Ali Nawaz, freelance WordPress and Shopify developer in Lahore, Pakistan (https://bealinawaz.com/about-me/).

Published: 2026-11-18

Public Shopify apps must switch to expiring offline access tokens by January 1, 2027. The deadlines, the exact migration and refresh requests, and Node.js code.

Every public Shopify app must use expiring offline access tokens for Admin API requests by **January 1, 2027**. On that day, apps still on non-expiring tokens are delisted from the Shopify App Store and blocked from new installs. From **April 1, 2027**, their Admin API requests return HTTP 403. Custom apps and apps a merchant creates for their own store are excluded. Migrating doesn't need merchants to reinstall: your backend exchanges each stored token for an expiring one with a single request, then refreshes it every hour.

Below are the dates, both requests exactly as shopify.dev documents them, and a small Node.js module that migrates a shop and keeps its token fresh. I tested it against a stub of the token endpoint that behaves as documented (rotating refresh tokens, `invalid_grant` errors).

## The deadlines

From Shopify's changelog ([May 20, 2026](https://shopify.dev/changelog/expiring-offline-access-tokens-required-for-all-public-apps-as-of-january-1-2027) and [October 27, 2026](https://shopify.dev/changelog/migrate-to-expiring-offline-access-tokens-before-january-2027)):

| Date | What happens |
|---|---|
| April 1, 2026 | Public apps **created** from this date must use expiring offline tokens |
| January 1, 2027 | All public apps must. Non-compliant apps are **delisted from the App Store and blocked from new installs**; existing installs keep working for now |
| January 15, 2027 | Merchants using a non-compliant app see warnings in their Shopify admin |
| April 1, 2027 | Admin API requests with non-expiring offline tokens return **HTTP 403** |

**Who's affected:** public apps that call the Admin API with an offline token. **Not affected:** custom apps and apps merchants create in the Dev Dashboard or Shopify admin for their own store. Those have their own changes, covered in [Shopify Admin API access token in 2026](https://bealinawaz.com/blog/shopify-admin-api-access-token/).

## What changes: the token pair

A non-expiring offline token was one `shpat_` string that worked forever. An expiring offline token comes as a pair:

| Field | Value | Meaning |
|---|---|---|
| `access_token` | `shpat_…` | Used for API calls, as before |
| `expires_in` | `3600` | Seconds until the access token expires (1 hour) |
| `refresh_token` | `shprt_…` | Used to get a new pair |
| `refresh_token_expires_in` | `7776000` | Seconds until the refresh token expires (90 days) |

Every refresh returns a **new** refresh token. Store it, and use the newest one next time. Shopify keeps the previous refresh token usable only until the replacement is first used ([August 28, 2026 changelog](https://shopify.dev/changelog/more-resilient-refreshes-for-expiring-offline-access-tokens)). That fallback is for recovering from a lost response, not for routine use.

## Step 1: get expiring tokens for new installs

When a shop installs or reauthorizes your app, request an expiring token by adding `expiring=1` to the token request.

If your app is built on the Shopify app template (React Router or Remix), turn on the future flag in `shopify.server.ts`. In `@shopify/shopify-app-react-router` 3.0.2 it defaults to `false`:

```ts
const shopify = shopifyApp({
  // ...
  future: {
    expiringOfflineAccessTokens: true,
  },
});
```

With the flag on, the library stores the refresh token and refreshes the access token when it's close to expiring. If you wrote your own OAuth code, add `expiring=1` to the authorization code or token exchange request for the offline token.

## Step 2: migrate the shops that are already installed

For each stored non-expiring token, make one token exchange request. This is the request from Shopify's [migration guide](https://shopify.dev/docs/apps/build/authentication-authorization/migrate-to-expiring-offline-access-tokens):

```bash
curl -X POST "https://{shop}.myshopify.com/admin/oauth/access_token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "subject_token={non_expiring_offline_token}" \
  -d "subject_token_type=urn:shopify:params:oauth:token-type:offline-access-token" \
  -d "requested_token_type=urn:shopify:params:oauth:token-type:offline-access-token" \
  -d "expiring=1"
```

Both `requested_token_type` and `expiring=1` are required. Save the returned pair and discard the old token. If your app crashes before saving the response, Shopify lets you retry the exchange with the original token within seven days, until the new pair has been refreshed.

## Step 3: refresh before the hour is up

```bash
curl -X POST "https://{shop}.myshopify.com/admin/oauth/access_token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "grant_type=refresh_token" \
  -d "refresh_token={refresh_token}"
```

The response has the same four fields plus `scope`. Shopify's [authorization code guide](https://shopify.dev/docs/apps/build/authentication-authorization/get-access-tokens/auth-code-grant/implement-auth-code-grants-manually) shows this request.

Refresh a few minutes before `expires_in` runs out, and also when an API call returns `401`. Shopify's advice is to run only one refresh at a time per shop and to save each new pair in a single write. Two refreshes racing for the same shop can leave you holding a retired refresh token.

## A Node.js module that does all three

`shopify-tokens.mjs` (Node 18+, no dependencies). `store` is your database with two methods, `get(shop)` and `set(shop, record)`:

```js
// shopify-tokens.mjs — expiring offline access tokens for a Shopify public app (Node 18+).
const REFRESH_MARGIN_MS = 5 * 60 * 1000; // refresh 5 minutes before the access token expires

async function tokenRequest(shop, params) {
  const response = await fetch(`https://${shop}/admin/oauth/access_token`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
    body: new URLSearchParams({
      client_id: process.env.SHOPIFY_API_KEY,
      client_secret: process.env.SHOPIFY_API_SECRET,
      ...params,
    }),
  });
  const body = await response.json().catch(() => ({}));
  if (!response.ok) {
    throw Object.assign(new Error(body.error_description || body.error || `HTTP ${response.status}`), {
      status: response.status,
      code: body.error,
    });
  }
  return body;
}

const toRecord = (token, now = Date.now()) => ({
  accessToken: token.access_token,
  refreshToken: token.refresh_token,
  expiresAt: now + token.expires_in * 1000,
  refreshExpiresAt: now + token.refresh_token_expires_in * 1000,
  scope: token.scope,
});

/** One-time migration: exchange the stored non-expiring token for an expiring pair. */
export async function migrateShop(shop, store) {
  const current = await store.get(shop);
  const token = await tokenRequest(shop, {
    grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
    subject_token: current.accessToken,
    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",
  });
  await store.set(shop, toRecord(token)); // one write replaces the old token
}

const refreshing = new Map(); // shop -> pending refresh, so a shop never refreshes twice at once

/** Returns a valid access token, refreshing it first when it's about to expire. */
export async function getAccessToken(shop, store) {
  const record = await store.get(shop);
  if (record.expiresAt - Date.now() > REFRESH_MARGIN_MS) return record.accessToken;

  if (!refreshing.has(shop)) {
    refreshing.set(
      shop,
      (async () => {
        try {
          const latest = await store.get(shop); // another request may have refreshed already
          if (latest.expiresAt - Date.now() > REFRESH_MARGIN_MS) return latest.accessToken;
          const token = await tokenRequest(shop, { grant_type: "refresh_token", refresh_token: latest.refreshToken });
          await store.set(shop, toRecord(token)); // save the new pair before using it
          return token.access_token;
        } finally {
          refreshing.delete(shop);
        }
      })(),
    );
  }
  return refreshing.get(shop);
}
```

Use it like this:

```js
import { migrateShop, getAccessToken } from "./shopify-tokens.mjs";

// Once per installed shop (for example in a migration script):
await migrateShop("demo.myshopify.com", store);

// Before every Admin API call:
const token = await getAccessToken("demo.myshopify.com", store);
await fetch("https://demo.myshopify.com/admin/api/2026-10/graphql.json", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Shopify-Access-Token": token },
  body: JSON.stringify({ query: "{ shop { name } }" }),
});
```

What I checked against the stub endpoint (it rotates refresh tokens and rejects a retired one with `invalid_grant`, as documented):

- The migration sends exactly the parameters above, including `expiring=1`, and stores the new pair.
- A token with more than 5 minutes left is returned without any request.
- 10 parallel calls for a token with 1 minute left made **one** refresh request, and all 10 got the same new token.
- An expired token is refreshed with the newest refresh token.
- A rejected refresh comes back as an error with `code: "invalid_grant"`.

**One server or many?** The `refreshing` map serializes refreshes inside one Node process. If several servers or workers share the same shops, take a lock per shop in your database (for example `SELECT … FOR UPDATE` on the shop's row) around the refresh instead.

## Common mistakes

- **Using the access token as `subject_token` to refresh.** Refreshing uses `grant_type=refresh_token` and the `refresh_token`. `subject_token` is only for token exchange.
- **Keeping the old refresh token.** Always save the pair from the latest response. Refreshing with an older one fails with `invalid_grant` once its replacement has been used.
- **Refreshing in parallel.** Two refreshes for the same shop at the same time can leave you holding a retired token. Serialize per shop.
- **Saving the access token and refresh token in two writes.** If the second write fails, they no longer match. Save both together.
- **Restoring an old database backup.** It can bring back refresh tokens that were already rotated. Back up token storage often, and plan for asking affected merchants to open the app again.

## FAQ

##### When do Shopify offline access tokens have to expire?

Public apps created from April 1, 2026 must already use expiring offline tokens. All other public apps must switch by January 1, 2027, when non-compliant apps are delisted and blocked from new installs. From April 1, 2027, Admin API requests with non-expiring offline tokens return HTTP 403.

##### Do custom apps need expiring offline tokens?

No. Shopify excludes custom apps and apps that merchants create in the Dev Dashboard or the Shopify admin. The rule applies to public apps.

##### Do merchants have to reinstall my app?

No. Your backend exchanges each stored non-expiring token for an expiring pair with one token exchange request.

##### How long do expiring offline tokens last?

The access token lasts 1 hour (`expires_in` is 3600). The refresh token lasts 90 days (`refresh_token_expires_in` is 7776000), and each refresh issues a new one.

##### What happens if a refresh token expires?

The refresh request fails with `invalid_grant`, and the app needs a new token through the normal authorization flow. That usually happens when the merchant opens the app again. Refresh regularly so active shops never reach the 90-day limit.

## When to get help

If your public app stores its own tokens, runs several workers, or uses an older library, I can migrate it and test the refresh path end to end. See [Shopify app development](https://bealinawaz.com/services/shopify-app-development/). Related: [Shopify legacy custom apps deprecated](https://bealinawaz.com/blog/shopify-legacy-custom-apps-deprecated/) and [the Admin API access token in 2026](https://bealinawaz.com/blog/shopify-admin-api-access-token/).
