DEV Community: Curythm

Building a Shopify app with Claude Code — spec-driven development and pricing design

Curythm — Sun, 03 May 2026 02:42:58 +0000

This is part 3 of a series on building MetaBulkify, a Shopify app for bulk editing metaobjects via CSV.

Part 1: Excel data corruption and GID/handle resolution
Part 2: Shopify platform traps (scopes, throttling, dev store billing)

This post is about two things: how I build software as a solo developer with AI, and how I designed pricing to let users try the app properly before committing.

How I actually build things

I have a day job. I code side projects on evenings and weekends. Time is the scarcest resource.

My workflow: I write detailed spec documents, then delegate implementation to Claude Code. Not prompts. Not "build me an app." Actual specs — 200+ line instruction documents covering data models, edge cases, error handling, security considerations.

Then Claude Code writes the code, and I review every line.

This is not "AI wrote my app." I make every architecture decision:

Which GraphQL mutations to use
How billing works
Where to put the usage tracking table
What happens when Cloud Tasks retries a failed job
Whether to fail-open or fail-closed on API errors

Claude Code is a fast pair programmer who never gets tired and never pushes back when I ask for a third rewrite.

What a spec doc looks like

For the billing system, my spec included:

A plan comparison table (Free vs Pro, exact limits)
Prisma schema for the usage tracking table
The exact GraphQL query for subscription detection
Error handling rules (fail-closed, count attempts not successes)
Idempotency requirements (Cloud Tasks retries must not double-count)
UI mockups in pseudocode (which Polaris Web Components to use, where to show banners)
Test steps (including "manually set DB value to 9999 and verify block")

Claude Code implemented the whole thing. I reviewed, found three issues, sent detailed feedback. Claude Code revised. I reviewed again, found one more issue, sent feedback. Third revision was clean. Shipped.

Three review rounds for billing alone. The bugs I caught:

Counting basis mismatch — blocking based on total rows, but recording only successful rows. This lets users retry failed imports to bypass the quota.
No idempotency guard — Cloud Tasks retries could double-count usage. Fixed with an atomic updateMany WHERE clause.
Soft cap instead of hard cap — "warning only" on Pro tier quota exceeded. Changed to hard block because a limit you don't enforce isn't a limit.

Each of these was a product decision, not a coding error. Claude Code implemented what I asked for. I asked for the wrong thing. The review process caught it.

The spec-driven advantage

Writing specs before coding forces you to think about edge cases upfront. "What happens if the import worker crashes after recording usage but before updating the job status?" is a question that naturally comes up when writing the spec. It rarely comes up when coding.

It also creates a paper trail. When something breaks in production, I can look at the spec and see whether the implementation deviated from the plan, or whether the plan itself was wrong.

And honestly, writing specs is faster than writing code. A 200-line spec takes me 2-3 hours. The implementation takes Claude Code 20 minutes. My review takes another hour. Total: ~4 hours for a feature that would take me 2-3 days to code manually.

Pricing design: letting users try before they commit

Bulk operation apps have a specific challenge. People don't use them every day — they need them when they need them. The pricing has to reflect that.

My solution:

	Free	Pro ($9.99/mo)
CSV Export	Unlimited	Unlimited
CSV Import	50 rows (lifetime)	10,000 rows/month

The thinking behind each decision:

Exports are free and unlimited. I want people to try the app with zero risk. Export your data, check the CSV format, see if it fits your workflow. If it doesn't work for you, you haven't paid anything.

50 free import rows. Enough to run a real test — pick a metaobject type, import a few entries, verify everything works in your store. You can confirm the app handles your field types, reference fields, and data format correctly before spending anything.

No free trial on Pro. Instead of a time-limited trial where you're racing the clock, the free tier gives you a permanent sandbox. Take your time. Test on Monday, come back Thursday, test again. No pressure.

$9.99/month for Pro. This is a focused tool that does one thing. The price reflects that — it's not trying to be a Swiss Army knife.

The numbers

Real talk:

Revenue: $9.99 (one subscription — they uninstalled after 2 hours due to a billing detection bug, not a pricing problem)
Infrastructure cost: effectively $0/month at current scale
Development time: a few weeks of evenings and weekends
Spec docs written: probably more words than actual code

Tech stack

For the curious:

React Router v7 + Shopify App Remix
Polaris Web Components (<s-banner>, <s-button> — not the React library)
Neon Postgres + Prisma
GCP Cloud Run + Cloud Tasks
JSON-based i18n (English + Japanese)

The infrastructure cost is near zero at current scale. When that changes, it'll mean the app is making money — which is a good problem to have.

What I'd do differently

Test with Excel-edited CSVs from day one. The normalization issue (Part 1) would have surfaced immediately.
Test billing on a real store, not a dev store. The dev store billing trap (Part 2) cost me a customer.
Ship with fewer features. I18n could have waited. The dry-run preview was essential; everything else was nice-to-have.
Start marketing before the app is "done." It's never done. I should have posted in Shopify community forums and dev.to weeks earlier.

Try MetaBulkify

Export and import Shopify metaobjects via CSV with dry-run preview.

→ MetaBulkify on the Shopify App Store

Free plan includes unlimited exports and 50 import rows.
I'm the developer — questions and feedback welcome in the comments.

Things Shopify doesn't tell you when building an app

Curythm — Sun, 03 May 2026 02:39:57 +0000

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

Try MetaBulkify

Export and import Shopify metaobjects via CSV with dry-run preview.

→ MetaBulkify on the Shopify App Store

Free plan includes unlimited exports and 50 import rows.
I'm the developer — questions and feedback welcome in the comments.

I built a Shopify app to bulk edit metaobjects — here's what broke

Curythm — Sun, 03 May 2026 02:29:49 +0000

Shopify metaobjects are great for structured data — size charts, materials, FAQs, store locators. But when you have dozens or hundreds of entries to manage, things get painful fast.

There's no CSV export. No bulk import. No "select all and change this field." You click into each entry one by one.

I hit this wall while managing metaobjects for a client's store. 50+ material entries, needed to update a field across all of them. After doing it manually for the third time, I started building MetaBulkify — a small app focused on CSV export/import for metaobjects with a dry-run preview.

Building it was fun. Debugging it was not. Here are the two hardest problems I ran into.

1. Excel silently rewrites your data

Export metaobjects to CSV. Open in Excel. Save. Import back. Every single row shows as "update."

Nothing changed, right? Wrong. Excel "helpfully" reformats values:

Type	Original	After Excel
date	`2025-01-01`	`2025/1/1`
integer	`1`	`1.0`
boolean	`true`	`TRUE`
date_time	`2025-01-01T10:00:00Z`	truncated or reformatted

A naive string comparison sees these as different values. I didn't realize the problem existed until I saw "45 updates, 0 unchanged" on a CSV I hadn't touched.

The fix was a normalizeForComparison() function that parses each value by type before comparing:

function normalizeForComparison(csvVal, existingVal, typeName) {
  if (csvVal === "" && existingVal === "") return ["", ""];

  switch (typeName) {
    case "date": {
      // "2025/1/1" and "2025-01-01" both become "2025-01-01"
      const csvDate = normalizeDate(csvVal);
      const exDate = normalizeDate(existingVal);
      if (csvDate && exDate) return [csvDate, exDate];
      return [csvVal, existingVal];
    }
    case "number_integer": {
      // "1" vs "1.0" — Number() parses both, Math.round drops the decimal
      const a = Number(csvVal), b = Number(existingVal);
      if (!isNaN(a) && !isNaN(b))
        return [String(Math.round(a)), String(Math.round(b))];
      return [csvVal, existingVal];
    }
    case "number_decimal": {
      // "1.50" vs "1.5" — Number() normalizes trailing zeros
      const a = Number(csvVal), b = Number(existingVal);
      if (!isNaN(a) && !isNaN(b)) return [String(a), String(b)];
      return [csvVal, existingVal];
    }
    case "boolean":
      // "TRUE" vs "true"
      return [csvVal.toLowerCase(), existingVal.toLowerCase()];
    default:
      return [csvVal, existingVal];
  }
}

// For list.* types, parse the JSON array and normalize each element
function normalizeListForComparison(csvVal, existingVal, typeName) {
  const innerType = typeName.replace(/^list\./, "");
  const csvArr = JSON.parse(csvVal || "[]");
  const exArr  = JSON.parse(existingVal || "[]");
  const normCsv = csvArr.map(v =>
    normalizeForComparison(String(v), "", innerType)[0]
  );
  const normEx = exArr.map(v =>
    normalizeForComparison(String(v), "", innerType)[0]
  );
  return [JSON.stringify(normCsv), JSON.stringify(normEx)];
}

Simple in retrospect. The lesson: if your app touches Excel at any point in the workflow, never compare raw strings.

2. CSV says "handle", Shopify says "GID" — and you need both

Metaobject reference fields store Shopify's internal GIDs like gid://shopify/Product/12345. But nobody wants to type GIDs in a spreadsheet. The CSV uses handles.

This creates a problem for the dry-run preview. You need to compare the CSV values against existing data to determine what changed. But you're comparing handles to GIDs. They'll never match.

My first implementation just gave up:

// For reference types, CSV has handle, existing has GID
// — can't compare directly.
// Mark as "potentially changed" (conservative approach)

Translation: every row with a reference field was marked as "update" even if nothing changed. Useless.

The fix required three steps:

Collect all reference GIDs from existing entries
Batch-resolve them to handles via nodes() queries (250 per request)
Replace GIDs with handles in a copy of the existing data, then compare

// Resolve GIDs to handles in batches of 250 (Shopify's hard limit per request)
async function resolveGidsToHandles(admin, gids) {
  const resolved = new Map();
  for (let i = 0; i < gids.length; i += 250) {
    const batch = gids.slice(i, i + 250);
    const resp = await admin.graphql(
      `query ResolveNodes($ids: [ID!]!) {
         nodes(ids: $ids) {
           id
           ... on Product    { handle }
           ... on Collection { handle }
           ... on Metaobject { handle }
         }
       }`,
      { variables: { ids: batch } },
    );
    const json = await resp.json();
    for (const node of json.data?.nodes ?? []) {
      if (node?.id && node?.handle) resolved.set(node.id, node.handle);
    }
  }
  return resolved;
}

And the reverse direction for import: resolve handles to GIDs before calling metaobjectUpsert. Each reference field type (product, collection, metaobject) needs its own resolution query.

For metaobject references, it gets worse — you need to know the target definition type (e.g., "author") to look up by handle. But the field definition only gives you a GID for the target definition. So that's another query:

// Query 1: field definition gives us a validation entry like
//   { name: "metaobject_definition_id",
//     value: "gid://shopify/MetaobjectDefinition/123" }
// That GID points at the *referenced* definition, not the type string.
const refDefIds = new Set();
for (const fd of fieldDefs) {
  if (fd.type.name === "metaobject_reference") {
    const v = fd.validations.find(v => v.name === "metaobject_definition_id");
    if (v?.value) refDefIds.add(v.value);
  }
}

// Query 2: resolve those definition GIDs → type strings (e.g. "author")
const resp = await admin.graphql(
  `query($ids: [ID!]!) {
     nodes(ids: $ids) { id ... on MetaobjectDefinition { type } }
   }`,
  { variables: { ids: [...refDefIds] } },
);

// Query 3 (per row): now we can finally call
//   metaobjectByHandle({ type: "author", handle: "shakespeare" })
// to get the GID that metaobjectUpsert actually needs.

Three queries deep just to resolve a reference field. Not documented anywhere as a pattern.

What's next

This is part 1 of a series on building MetaBulkify. Coming up:

Part 2: Things Shopify doesn't tell you when building an app — OAuth scope traps, 200 OK that actually means throttled, and dev stores that lie about subscriptions
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

Try MetaBulkify

Export and import Shopify metaobjects via CSV with dry-run preview.

→ MetaBulkify on the Shopify App Store

Free plan includes unlimited exports and 50 import rows.
I'm the developer — questions and feedback welcome in the comments.