DEV Community: LunJaiii

Your Shopify app's real OAuth problem isn't Shopify — it's the other API

LunJaiii — Mon, 06 Jul 2026 06:17:38 +0000

Every Shopify tutorial covers the same OAuth dance: merchant installs, you get a token, done. The framework handles 100% of it.

Then you build a real app. A real app connects to something — Xero, QuickBooks, Klaviyo, an ERP, a shipping API — because an app that only talks to Shopify is rarely worth $19/month. And that second OAuth integration is 100% yours. No framework, no guardrails.

I shipped a Shopify-to-Xero sync app. Here are the four failure modes that only showed up days or weeks after things "worked", and the patterns that survive them.

1. Refresh tokens rotate — persist BOTH tokens, every refresh

Many providers (Xero included) issue a new refresh token every time you use one. If your refresh handler only saves the new access token, everything works... until the next refresh, when your stored refresh token turns out to be single-use and already spent. The connection dies silently. The merchant blames your app.

const updated = await db.partnerConnection.update({
  where: { shop },
  data: {
    accessToken: encryptSecret(tokens.access_token),
    refreshToken: encryptSecret(tokens.refresh_token), // rotation!
    expiresAt: new Date(Date.now() + tokens.expires_in * 1000),
  },
});

2. Refresh tokens die of loneliness — keep-alive cron

Xero's refresh tokens expire after ~60 idle days. Think about who goes idle: a merchant with a seasonal shop installs in January, goes quiet, comes back for the summer rush — dead connection, angry merchant, support ticket.

Fix: a weekly cron that force-refreshes every stored connection, regardless of expiry. Our getValidConnection(shop, { force: true }) flag exists purely for this keep-alive job.

3. Refresh proactively, not on 401

Refreshing 60 seconds before expiry instead of reacting to a 401 saves you a failed call + retry — which matters a lot during a webhook burst (a flash sale means dozens of order webhooks, each wanting an API call).

if (!opts.force && conn.expiresAt.getTime() - 60_000 > Date.now()) {
  return decrypted(conn); // still fresh
}
// otherwise refresh now, before the API call

4. Rate limits: evenly-spaced throttle + Retry-After

Partner APIs limit per tenant (Xero: 60/min). You don't control your traffic — Shopify webhooks do. Two layers:

// Layer 1: never hit the limit — evenly space calls
let nextSlot = 0;
async function throttle() {
  const gapMs = Math.ceil(60_000 / CALLS_PER_MINUTE) + 100;
  const wait = Math.max(0, nextSlot - Date.now());
  nextSlot = Math.max(Date.now(), nextSlot) + gapMs;
  if (wait > 0) await new Promise(r => setTimeout(r, wait));
}

// Layer 2: if a 429 slips through, honour Retry-After (up to 3 attempts)
if (res.status === 429 && attempt < 3) {
  const retryAfter = parseInt(res.headers.get("Retry-After") ?? "2", 10);
  await new Promise(r => setTimeout(r, retryAfter * 1000));
}

Bonus gotchas

The consent screen can't run inside the Shopify admin iframe. Open it in a new tab, and carry the shop domain through the round-trip in the state param — the callback lands in a bare tab with no session you can trust.
Encrypt tokens at rest. Shopify's protected-customer-data expectations (and basic hygiene) mean your partner's refresh token shouldn't sit in plaintext in Postgres. AES-256-GCM with a versioned prefix lets you turn encryption on after launch without a migration.
Design the reconnect UX on day one. Connections die (revoked, expired, account closed). A null connection should render a "Reconnect" button, not crash a dashboard — and failed jobs should self-heal via a retry cron once the merchant reconnects.

Where this comes from

These patterns are lifted from the production code of my Shopify-to-Xero app, and they're the core of chapter 4 of ApprovedKit — a boilerplate that layers production-tested modules (billing, GDPR webhooks, this whole OAuth module, a $5 VPS deploy stack) on top of Shopify's official template, plus a live log of our App Store review as it happens.

Early access is $99 for the first 30 seats at approvedkit.com. And even if you never buy anything: persist both tokens. Future you will thank present you.

Your brand-new Shopify app template ships with a TypeScript error (and the one-line fix)

LunJaiii — Mon, 06 Jul 2026 06:16:00 +0000

Run this today:

shopify app init   # choose Remix
cd your-app && npm install && npx tsc --noEmit

and there's a good chance you'll be greeted by this wall:

app/shopify.server.ts: error TS2322: Type 'PrismaSessionStorage<PrismaClient<...>>'
is not assignable to type 'SessionStorage'.
  Types of property 'storeSession' are incompatible.
    ...
      Types have separate declarations of a private property 'compressedScopes'.

You haven't written a single line of code yet. Welcome to Shopify app development.

What's actually happening

That last line is the tell: "separate declarations of a private property" means TypeScript is comparing two different copies of the same class from two different places in node_modules.

Check it:

npm ls @shopify/shopify-api

On a fresh template you'll see two versions. As of this writing:

@shopify/shopify-app-session-storage-prisma@8 depends on @shopify/shopify-api@^12
@shopify/shopify-app-remix@4 bundles @shopify/shopify-api@^13

Those ranges don't overlap, so npm installs both — one at the top level, one nested under shopify-app-remix. Your PrismaSessionStorage is built against v12's Session class; the shopifyApp() config expects v13's. Same class name, different declarations, TypeScript (correctly) refuses.

Things that don't fix it

npm dedupe — can't collapse a genuine semver conflict. Tried it, still duplicated.
Deleting node_modules and reinstalling — same resolution, same result.
as any on the session storage — compiles, and now you've turned off type checking on the exact seam where your auth sessions live.

The one-line fix

npm install @shopify/shopify-app-session-storage-prisma@^9

v9 peers against @shopify/shopify-api@^13. The nested copy disappears, and:

npm ls @shopify/shopify-api   # exactly ONE version
npx tsc --noEmit              # green

The related mystery cast you'll see in older code

If you've read open-source Shopify apps, you may have seen billing plan names cast like this:

await billing.require({
  plans: [MONTHLY_PLAN as never],   // ← why??
  ...
});

Same root cause. With two @shopify/shopify-api copies, billing plan-name type inference breaks, and as never was the workaround that let people ship. With a single copy, the cast is unnecessary (though harmless).

Why I'm writing this down

I'm building ApprovedKit — a Shopify app boilerplate extracted from a real production app (currently going through App Store review, and we're logging the whole review process live). While verifying that our modules apply cleanly to a fresh official template, we hit this exact error on a clean clone — which means every new Shopify app developer hits it too.

That's the kit's whole philosophy: every gotcha we hit becomes a documented fix at the exact line it matters. If that sounds useful, the early-access version is $99 for the first 30 seats.

Happy shipping — and run npm ls @shopify/shopify-api before you trust your types.