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.

TL;DR

• JSON metafield writes capped at 128KB for API 2026-04+
• All other metafield types unchanged (current limits still apply)
• Existing apps (created before April 1, 2026) are grandfathered at 2MB
• Reads are unaffected — large values remain readable by all API versions
• New apps can request exceptions via Shopify's form
• Originally announced as 16KB — revised to 128KB after developer backlash

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.

Frequently Asked Questions

Does this affect all metafield types?

No. Only JSON type metafields. String, integer, URL, and all other types keep their existing limits.

What happens to existing large metafields?

They remain readable. You can still fetch them via any API version. But if you try to update an oversized value using API 2026-04+, the write will be rejected.

Are existing apps really grandfathered?

Yes. Apps created before April 1, 2026 keep the current 2MB limit for JSON metafields, regardless of which API version they use.

Does this affect Liquid or theme metafield access?

No. Liquid reads are unaffected. This only limits API writes.

What if I'm not sure if my metafields exceed 128KB?

Run the audit query above. Most stores have zero metafields over 128KB. The limit targets extreme outliers.

Source: Shopify Developer Changelog — February 19, 2026 (shopify.dev/changelog/reduced-metafield-value-sizes)