Shopify's JSON Metafield 128KB Cap: What Developers Need to Know

Starting with API version 2026-04 (April 1, 2026), Shopify is capping JSON metafield writes at 128KB. If you're storing large JSON blobs in metafields, this affects you.

But before you panic — there's a grandfathering clause. And the limit was originally much worse.

The Backstory

On February 19, 2026, Shopify announced JSON metafield values would be limited to 16KB. The developer community reacted immediately — 16KB is tiny. A moderately complex product configuration, a theme settings object, or a multi-language content block can easily exceed that.

Shopify listened. They revised the limit to 128KB, which accommodates the vast majority of real-world use cases while still preventing the actual problem: metafields bloated to megabytes that tank storefront performance.

Why Shopify Did This

The official reasoning: large JSON metafields hurt storefront performance. When multiple large metafield values load together on a single page, you can end up fetching tens of megabytes of data. That's a performance disaster — especially on mobile.

Most metafield values are small. The stores causing problems are the outliers with 500KB+ JSON blobs crammed into metafields. This limit targets those cases without affecting normal usage.

Who's Actually Affected?

Not affected (most developers):

• Apps created before April 1, 2026 — grandfathered at 2MB
• Anyone storing JSON under 128KB (the vast majority)
• Non-JSON metafield types (string, integer, URL, etc.)
• Reading large metafields — reads are unlimited

Potentially affected:

• New apps built after April 2026 that need large JSON storage
• Existing apps that switch to API 2026-04+ with oversized JSON values
• Stores with bulk-imported product data in JSON metafields

The 2-Minute Audit

Find your largest JSON metafields:

query {
  shop {
    metafieldDefinitions(first: 50, type: "json") {
      edges {
        node {
          namespace
          key
          ownerType
        }
      }
    }
  }
}

Then check sizes programmatically:

// Node.js — check metafield sizes
const metafields = await shopify.rest.Metafield.all({
  namespace: 'your-namespace',
  owner_resource: 'shop',
});

const oversized = metafields.filter(m => {
  const size = new TextEncoder().encode(
    typeof m.value === 'string' ? m.value : JSON.stringify(m.value)
  ).length;
  return size > 131072; // 128KB
});

console.log(`${oversized.length} metafields exceed 128KB`);
oversized.forEach(m =>
  console.log(`  ${m.namespace}.${m.key}: ${(JSON.stringify(m.value).length / 1024).toFixed(1)}KB`)
);

Migration Strategies

If you do have oversized metafields, here are your options:

Option 1: Split Into Multiple Metafields (Recommended)

Break one large JSON into several smaller, logical pieces. In Liquid, the access pattern barely changes:

{% comment %} Before: one big metafield {% endcomment %}
{% assign config = shop.metafields.my_app.config.value %}
{{ config.theme_settings.primary_color }}

{% comment %} After: separate metafields {% endcomment %}
{% assign theme = shop.metafields.my_app.theme_settings.value %}
{{ theme.primary_color }}

Option 2: Use Shopify Files for Large Data

Store large datasets as files, keep only the reference in a metafield:

// Store the file URL in a tiny metafield
await shopify.rest.Metafield.create({
  namespace: 'config',
  key: 'data_url',
  value: 'https://cdn.shopify.com/s/files/.../config.json',
  type: 'url'
});

Works well for rarely-changing data. Downside: requires a second fetch to get the actual content.

Option 3: External Database + Reference

For dynamic, frequently-changing large data: store in Firestore, Supabase, or your own database. Keep only an ID/reference in the metafield. Sync via webhooks. Best for apps that already have a backend.

Option 4: Request an Exception

If you're building a new app with a legitimate need for >128KB JSON metafields, Shopify will grant exceptions case-by-case. Fill out their request form on the changelog post.

Timeline

• February 19, 2026: Announced (originally 16KB, revised to 128KB)
• Now: API 2026-04 available for testing
• April 1, 2026: API 2026-04 released — 128KB limit enforced on new writes
• July 1, 2026: API 2026-04 becomes default version
• October 1, 2026: API 2025-10 deprecated — forced migration

Important: Apps created before April 1 are grandfathered at 2MB regardless of which API version they use. The 128KB limit primarily affects newly created apps.

The Bottom Line

For most developers, this changes nothing. Your metafields are probably well under 128KB, and if your app existed before April 2026, you're grandfathered anyway.

For new app developers, 128KB is generous for most use cases. If you need more, split your data or request an exception.

The real lesson: don't use metafields as a general-purpose database. They're for metadata — small, focused pieces of information attached to Shopify resources. If you're storing megabytes of JSON in a metafield, you probably need a different architecture anyway.

My Shopify review angle

When I would review this in a client Shopify store, I would start with the operational surface instead of the headline. Shopify's JSON Metafield 128KB Cap: What Developers Need to Know only becomes useful when the reader can map it to a theme file, app setting, Admin API job, checkout rule, or storefront behavior they can actually test.

I would not leave this as theory. I would apply it to one actual page, integration, bug, or client decision and keep the evidence beside the recommendation.

Pre-launch Shopify checks

• Check the exact Shopify surface before changing code.
• Test with products that have missing images, long variants, empty metafields, and unusual prices.
• Confirm the change is visible in server-rendered HTML where SEO/AEO matters.
• Keep a rollback path for app or theme changes.
• Write a handoff note so the merchant team knows what can be edited safely.

Edge cases in the store

• The article sounds correct but does not explain what to edit in Shopify.
• The guidance ignores app conflicts, API versions, or messy product data.
• The change helps desktop screenshots but hurts mobile checkout.
• The page makes a claim that is not backed by visible content or schema.

Merchant handoff block

Implementation check for Shopify's JSON Metafield 128KB Cap: What Developers Need to Know:
1. Confirm the Shopify surface involved: theme, Admin API, checkout, app, or storefront.
2. Test with messy catalog data, not only a demo product.
3. Verify permissions, API version, and rollback path.
4. Record the production edge case this change protects.

A short review block like this is often enough to catch the gap between a nice idea and a safe production change.

Where I would add more proof

I would keep improving this page by replacing any remaining abstraction with artifacts from actual work: test output, screenshots, metrics, source references, or before/after notes.