---
title: Metafield limits
description: Limits on metafields available per merchant store.
source_url:
  html: 'https://shopify.dev/docs/apps/build/metafields/metafield-limits'
  md: 'https://shopify.dev/docs/apps/build/metafields/metafield-limits.md'
---

# Metafield limits

This document outlines the various limits for metafields and their definitions per shop, including apps.

### Metafield definition limits

**Note:**

Standard metafield definitions don't count towards limits unless specified.

#### App definitions

Each app installed on a shop can create up to 256 metafield definitions per resource type.

#### Merchant definitions

Merchants can create up to 256 metafield definitions per resource type.

#### Other limits

| Limit type | Limit |
| - | - |
| Pinned definitions limit per resource type | 50 |

### Metafield type size limits

**Info:**

Apps using JSON fields before April 1, 2026 will be grandfathered at the current 2MB limit. New apps requiring >128KB JSON fields may request an exception via [this form](https://docs.google.com/forms/d/e/1FAIpQLSdMEzS4NoKB3BfL3gjQMRhPT3ZNtZipzuBxVWy8SqJCYYBkMw/viewform).

Most metafield types have a 64KB (65,536 bytes) size limit, with the following exceptions:

| Type | Size limit |
| - | - |
| `id` | 2KB |
| `json` | 128KB |
| `url` | 2KB |

**Note:**

Single line text metafield predefined choices are limited to 128 values.

**Caution:**

[Shopify Functions input queries](https://shopify.dev/docs/api/functions/latest#input-query-limits) don't return metafield values larger than 10,000 bytes. The value is still stored, and the GraphQL Admin API still returns it, but a function receives `null` for it.

### Lists type limits

All [list types](https://shopify.dev/docs/apps/build/metafields/list-of-data-types#list-types) have a maximum of 128 items except metaobject references, which support up to 1024 items.

**Note:**

* Each item in the list has the same size limits as its corresponding single value type. For example, each text field in a `list.single_line_text_field` can store up to 64KB (65,536 bytes).
* You can use the `list.min` and `list.max` validations through the GraphQL Admin API to set custom minimum and maximum limits for the number of items in a list, as long as they don't exceed the maximum size limits.

**Note:**

In Liquid, a loop over a list of references, such as `list.product_reference`, `list.file_reference`, or `list.metaobject_reference`, returns only the first 50 items. To access more items, use the [`paginate`](https://shopify.dev/docs/api/liquid/tags/paginate) tag, which returns up to 250 items per page. For the limits on loading metaobjects in Liquid, refer to [Metaobject limits](https://shopify.dev/docs/apps/build/metaobjects/metaobject-limits#liquid-limits).

### Metafield definition capability limits

| Limit type | Limit |
| - | - |
| Used to power smart collections | 128 |
| Use as admin filter on Products, Companies, Company Locations, or Metaobjects | 50 |
| Use as admin filter on Orders | 5 |

**Note:**

Metafield definition capabilities extend metafield functionality. Learn more about [metafield capabilities](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities).

### Batch operation limits

The GraphQL Admin API limits how many metafields you can include in a single request:

| Operation | Limit |
| - | - |
| [`metafieldsSet`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldsSet) | 25 metafields per request, with a maximum total payload size of 10MB |
| [`metafieldsDelete`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldsDelete) | 250 metafields per request |

The `metafieldsDelete` limit comes from the platform-wide [maximum input array size](https://shopify.dev/docs/api/usage/limits#input-limits), which applies to any argument that accepts an array.

### Calculated query cost

[`metafieldsSet`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldsSet) doesn't have a fixed [calculated query cost](https://shopify.dev/docs/api/usage/limits#cost-calculation). Shopify does a varying amount of work for each resource whose metafields change, so the cost of a request depends on how many distinct owners it writes to:

cost = 10 + Σ (number of distinct owners of a type × that type's weight)

| Owner type | Weight |
| - | - |
| `Order` | 10 |
| `Product` | 4 |
| `ProductVariant` | 2 |
| `Collection` | 1 |
| `Customer`, `CustomerSegmentMember` | 1 |
| `Shop` | 1 |
| All other owner types | 0 |

An owner is counted once per mutation invocation, regardless of how many metafields are set on it. For example, a mutation that sets two metafields on one product, one metafield on a second product, and one metafield on a product variant has two distinct `Product` owners and one distinct `ProductVariant` owner, so it costs `10 + (2 × 4) + (1 × 2)` = 20 points. Because a mutation is limited to 25 metafields, the highest cost a single `metafieldsSet` invocation can reach is 260 points.

**Caution:**

Cost is calculated per `metafieldsSet` invocation, not per request. When using [GraphQL aliases](https://shopify.dev/docs/api/usage/graphql-basics/queries#aliases) to send multiple `metafieldsSet` mutations in a single request, the base cost of 10 is charged for each alias, and owners are not deduplicated across aliases. A request with three aliases updating the same 25 distinct orders costs 780 points `3 × (10 + 25 × 10)`.

**Note:**

Because of the base cost per invocation, setting all of a resource's metafields in one mutation invocation is always cheaper than sending one mutation per metafield.

***