“Metafields are fields, metaobjects are objects” is true and no help when you’re deciding where “Care instructions” should live on a 2,000-product catalog. Put it in a product metafield and you’ve got 2,000 copies of the same four paragraphs. Put it in a metaobject and you’ve got one entry, a reference on each product, and one place to fix the typo.
The real question isn’t what the data is. It’s whether it belongs to one product or is shared by many, and what has to happen the day it changes. Here are the six questions we use on client catalogs, worked through on real examples, plus the limits that should shape the decision before you build anything.
The difference in one line
Shopify’s developer docs explain it with a database analogy, and it’s the clearest version we know:
| Database concept | Shopify equivalent | Example |
|---|---|---|
| Built-in table | Resource | Product, Collection, Customer, Order |
| Column on a built-in table | Metafield definition | “Fabric weight” on Product |
| Custom table | Metaobject definition | “Designer”, “Size chart” |
| Column on a custom table | Metaobject field | “Bio” on Designer |
| Row | Metaobject entry | The designer “Ana Ruiz” |
| Foreign key | Reference field | A product’s custom.designer pointing at an entry |
A metafield adds a column to something Shopify already has. A metaobject adds a new kind of record. Most real catalogs need both, joined by reference fields: a product metafield of type metaobject_reference that points at an entry.
Six questions that decide it
| Question | If yes | Example |
|---|---|---|
| Is it an attribute of one resource only? | Metafield | A product’s weight; a variant’s barcode note |
| Is the same content shared by many resources? | Metaobject, plus a reference metafield on each resource | Care instructions used by 300 products |
| Do several values belong together? | Metaobject | A designer: name, bio, photo, link |
| Does it need its own page and URL? | Metaobject with web pages turned on | Designer profile pages |
| Should editors pick from a fixed set? | Metaobject reference (or a metafield with preset choices for simple lists) | Fit type: slim, regular, relaxed |
| Does the relationship itself carry data? | An intermediate metaobject | An ingredient plus its quantity in a recipe |
When a piece of data gets a “yes” on more than one row, the metaobject answer usually wins. The first row is the only one that points cleanly at a metafield.
Worked examples from one catalog
Take an apparel store with a few thousand products.
Care instructions: shared, so a metaobject
There are maybe twelve distinct sets of care instructions across the whole catalog. Each becomes an entry in a care_instructions definition (title, instructions as rich text, an icon). Each product gets a custom.care metafield of type metaobject_reference that points at one of them. Rewording the wool instructions is now one edit, not three hundred.
Dimensions: per product, so a metafield
A product’s packed dimensions belong to that product alone. A dimension metafield on Product stores the value and its unit. Making it a metaobject would mean one entry per product, which is a metafield with extra steps.
Designers: reusable, structured, and they need pages
Designers have several fields, are shared across products, and deserve their own pages. That’s a metaobject definition with the web pages option turned on (the renderable and onlineStore capabilities in the API). Each entry gets a URL of the form /pages/{url-handle}/{entry-handle}, for example /pages/designers/ana-ruiz, rendered with a theme template. Products point at their designer with a custom.designer reference metafield.
Fabric and color: check category metafields first
Before building a “Fabric” definition, assign product categories from Shopify’s standard product taxonomy. Categories come with category metafields such as fabric, color and neckline, backed by metaobject entries Shopify provides, which you can use as-is or customize. They don’t count toward your definition limit, and other parts of Shopify understand them. Build your own only for what’s specific to your catalog.
What choosing wrong costs
Shared text copied into a metafield on every product
The most common mistake, and the one that hurts slowly. Every wording change becomes a catalog-wide edit, copies drift apart, and nobody knows which version is current. Moving it into a metaobject later means de-duplicating thousands of values first.
A handle typed into a text field to fake a link
Storing ana-ruiz in a single_line_text_field and treating it as a reference looks harmless. Shopify’s data-modeling docs warn against it: Liquid and the Storefront API can’t resolve a text value into the object it names, so the theme has to look the entry up by hand, if it can at all. Use a reference field.
Over-normalizing
The opposite failure. A size chart that references rows, which reference measurement types, which reference units, is correct and miserable. Every level makes the admin harder to edit, imports need another pass, and deeply nested references can run into the Storefront API’s query nesting limits on headless builds. Stop at the level where the data actually gets reused.
Limits to check before you build
Shopify’s current limits for metaobjects:
| Limit | Value |
|---|---|
| Fields per metaobject definition | 40 |
| Entries per definition | 1,000,000 |
| Merchant-created definitions per store | 128 on Basic, Shopify and Advanced; 256 on Plus |
| Metaobjects in one list reference | 1,024 |
Entries a Liquid loop returns without paginate |
50 |
Standard definitions (including the ones behind category metafields) don’t count toward the definition limit. The one that catches teams out is the last row: a list reference can hold 1,024 entries, but a theme loop shows the first 50 unless it’s paginated.
Translations and markets behave differently
This often decides the model on international stores.
- Translation works on text-like fields: single-line and multi-line text, rich text, URLs, links, JSON, and file references. It doesn’t apply to numbers, measurements, or product, collection and metaobject references.
- Market localization is the opposite: a product metafield that holds a
metaobject_referencecan point at a different entry per market. A US market can show the inches chart and the EU market the centimeters chart, from the same product.
So if your content differs by language, translate the fields. If it differs by market (units, compliance text, a regional supplier), keep separate entries and localize the reference. Translating metaobjects covers both in detail.
The short version
- One resource owns it → metafield.
- Shared, structured, needs a page, or picked from a set → metaobject plus a reference.
- The relationship has its own data → an intermediate metaobject.
- Check standard category metafields before inventing your own.
For the full picture (relationship patterns, reference architectures and a migration path for an existing store), read the guide to structuring custom data on Shopify. If you’re moving size charts or spec tables out of product descriptions, migrating size guides into metaobjects has the step-by-step.