Things Shopify doesn't tell you when building an app

#shopify #webdev #javascript #beginners

I recently shipped MetaBulkify, a Shopify app for bulk editing metaobjects via CSV. (Part 1 covers the metaobject-specific challenges.)

The metaobject stuff was hard, but the Shopify platform stuff was harder. Here are three traps that aren't obvious from the docs.

1. OAuth scopes are two things that look like one thing

Week 1 of development. Nothing works. metaobjectDefinitions query returns an empty array. No error message. Just... nothing.

The problem? read_metaobjects and read_metaobject_definitions are completely separate OAuth scopes. Having one does not give you the other. And the naming is close enough that you'd assume they're the same.

But it gets worse. Shopify apps have two places to declare scopes:

shopify.app.toml (the config file)
shopify.server.ts (the runtime config)

I fixed the TOML file. Still broken. Turns out shopify.server.ts reads from process.env.SCOPES?.split(","), which was undefined. Nine debugging attempts before I found it.

And even after fixing both, the old OAuth token was cached in the database with the old scopes. So the full recovery was:

Fix both config files
Deploy
Delete the session record from the database
Restart the app
Reinstall the app on the dev store

Five steps to change a scope. If you're seeing empty responses from Shopify's GraphQL API, check your scopes first — and check both places they're declared.

2. Shopify returns 200 OK on throttled requests

Shopify's GraphQL Admin API uses a leaky bucket rate limiter. When you exceed it, you'd expect an HTTP 429 status code.

Nope. You get 200 OK. The throttle signal is buried in the response body:

{
  "errors": [
    {
      "message": "Throttled",
      "extensions": { "code": "THROTTLED" }
    }
  ]
}

If your code checks response.ok or response.status === 200 and assumes success, throttled requests will silently fail. I hit this immediately because MetaBulkify imports metaobjects one at a time (the API doesn't support bulk mutations for metaobjectUpsert), so any import over ~40 rows starts bumping into the rate limit.

The fix is exponential backoff:

async function graphqlWithRetry(admin, query, variables, maxRetries = 5) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const resp = await admin.graphql(query, { variables });
      const json = await resp.json();

      // 200 OK but actually throttled — check the errors array
      const isThrottled = json.errors?.some(
        e => e.extensions?.code === "THROTTLED"
          || e.message?.includes("Throttled"),
      );

      if (isThrottled && attempt < maxRetries) {
        const delayMs = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s, 8s, 16s
        await sleep(delayMs);
        continue;
      }
      return json;
    } catch (err) {
      // Network errors: retry up to 3 times, then let the caller fail
      if (attempt < Math.min(maxRetries, 3)) {
        await sleep(Math.pow(2, attempt) * 1000);
        continue;
      }
      throw err;
    }
  }
  throw new Error("Max retries exceeded");
}

Standard retry logic, but you need to know to look inside a 200 response for errors. This tripped me up for a while.

3. Dev stores lie about subscriptions

This one cost me my first paying customer.

Shopify development stores support "test charges" for app billing. When a merchant subscribes to your Pro plan on a dev store, the admin UI clearly shows: "Pro — Active."

So naturally, your app queries the subscription status via GraphQL:

query {
  currentAppInstallation {
    activeSubscriptions { id name status }
  }
}

And gets back: empty array.

The admin UI says Active. The API says nothing exists. Your app thinks the merchant is on the free plan.

My first real customer subscribed to Pro ($9.99/month), tried to use Pro features, was blocked by the free tier limit, left a review: "Not working properly with store," and uninstalled within 2 hours.

The fix: also query shop.plan.partnerDevelopment in the same request.

query {
  shop { plan { partnerDevelopment } }
  currentAppInstallation {
    activeSubscriptions { id name status }
  }
}

If partnerDevelopment === true, the store is a dev store — auto-grant Pro. Real production stores with real payments show up correctly in activeSubscriptions.

const partnerDev = data?.data?.shop?.plan?.partnerDevelopment === true;
if (partnerDev) {
  return { plan: "pro", subscriptionId: null }; // dev store → free Pro
}
// Otherwise, check activeSubscriptions as normal

If you're building a Shopify app with Managed Pricing: test your billing flow on a real (non-dev) store before shipping. A Shopify Starter plan costs $5/month and will save you from this exact trap.

Bonus: fail-closed billing

Related to the billing topic — what happens when Shopify's API goes down and your app can't check the subscription status?

Fail-open (default to Pro): everyone gets free access during outages. Bad.
500 error: the whole app breaks. Also bad.
Fail-closed (default to Free): Pro users might be temporarily restricted, but nobody gets access they shouldn't have.

export async function getBillingStatus(admin, shop) {
  try {
    const response = await admin.graphql(/* ... */);
    // ... parse subscription status
  } catch {
    // Shopify API down → restrict to free tier (fail-closed)
    return { plan: "free", subscriptionId: null };
  }
}

Three lines of try/catch. Easy to forget, painful to learn the hard way.

What's next

This is part 2 of a series on building MetaBulkify.

Part 1: I built a Shopify app to bulk edit metaobjects — here's what broke — Excel data corruption and GID/handle resolution
Part 3: Building a Shopify app with Claude Code — spec-driven development with AI, and how I designed the pricing to let users try before they commit