Metafield limits
This document outlines the various limits for metafields and their definitions per shop, including apps.
Anchor to Metafield definition limitsMetafield definition limits
Standard metafield definitions don't count towards limits unless specified.
Standard metafield definitions don't count towards limits unless specified.
Anchor to App definitionsApp definitions
Each app installed on a shop can create up to 256 metafield definitions per resource type.
Anchor to Merchant definitionsMerchant definitions
Merchants can create up to 256 metafield definitions per resource type.
Anchor to Other limitsOther limits
| Limit type | Limit |
|---|---|
| Pinned definitions limit per resource type | 50 |
Anchor to Metafield type size limitsMetafield type size limits
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.
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.
Most metafield types have a 64KB (65,536 bytes) size limit, with the following exceptions:
| Type | Size limit |
|---|---|
id | 2KB |
json | 128KB |
url | 2KB |
Single line text metafield predefined choices are limited to 128 values.
Single line text metafield predefined choices are limited to 128 values.
Shopify Functions input queries 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.
Shopify Functions input queries 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.
Anchor to Lists type limitsLists type limits
All list types have a maximum of 128 items except metaobject references, which support up to 1024 items.
- 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_fieldcan store up to 64KB (65,536 bytes). - You can use the
list.minandlist.maxvalidations 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.
- 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_fieldcan store up to 64KB (65,536 bytes). - You can use the
list.minandlist.maxvalidations 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.
Anchor to Metafield definition capability limitsMetafield 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 |
Metafield definition capabilities extend metafield functionality. Learn more about metafield capabilities.
Metafield definition capabilities extend metafield functionality. Learn more about metafield capabilities.
Anchor to Batch operation limitsBatch operation limits
The GraphQL Admin API limits how many metafields you can include in a single request:
| Operation | Limit |
|---|---|
metafieldsSet | 25 metafields per request, with a maximum total payload size of 10MB |
metafieldsDelete | 250 metafields per request |
The metafieldsDelete limit comes from the platform-wide maximum input array size, which applies to any argument that accepts an array.
Anchor to Calculated query costCalculated query cost
metafieldsSet doesn't have a fixed calculated query cost. 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:
| 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.
Cost is calculated per metafieldsSet invocation, not per request. When using GraphQL 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).
Cost is calculated per metafieldsSet invocation, not per request. When using GraphQL 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).
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.
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.