Shopify custom data
Shopify Metafields vs. Metaobjects: what's the difference?
Metafields and Metaobjects are both part of Shopify's custom data layer, but they serve different purposes and are often confused with each other. This article explains what each one is, how they differ architecturally, and when to reach for one versus the other - with Liquid and GraphQL examples for both.
Audience: Shopify developers, technical merchants, theme developers. Reading time: ~8 minutes.
1. What are Metafields?
Metafields extend existing Shopify resource types - products, variants, collections, customers, orders, pages, and more - with additional custom properties. They are key/value pairs attached to a specific resource instance.
For example:
- A product can have a Metafield for
care_instructions(a text field) - A product variant can have a Metafield for
weight_kg(a number field) - A customer can have a Metafield for
loyalty_tier(a text field)
Metafields are namespaced: each one belongs to a namespace and has a key. The full address of a Metafield on a product is product.metafields.namespace.key. They extend an existing thing - they do not create new things.
2. What are Metaobjects?
Metaobjects are standalone custom data types that you define and instantiate independently of Shopify's built-in resource types. They are not attached to a product or customer - they exist as their own entities in your store.
You define a Metaobject type (called a definition) with named, typed fields. Then you create as many instances of that type as you need. Each instance is a Metaobject record with its own handle identifier and field values.
Examples of things you would model as Metaobjects (not Metafields):
- Product reviews (each review is its own record: rating, body, author, date)
- Team members (name, role, photo, bio)
- FAQ entries (question, answer)
- Testimonials (quote, attribution, company)
- Store locations (name, address, hours)
Metaobjects are queried globally - not as properties of a specific resource. They have their own API endpoints and their own Liquid access patterns.
3. The key conceptual difference
The clearest way to distinguish them:
- Metafield: adds a property to something that already exists. "This product has a care instructions field."
- Metaobject: creates a new thing entirely. "A product review is an entity in my store, linked to a product."
A product review cannot be a Metafield because a store has many reviews per product, and Metafields hold a single value per key. A Metaobject is the correct structure because it is an independent record that can reference a product via a product_reference field.
| Property | Metafield | Metaobject |
|---|---|---|
| Attached to | An existing resource (product, customer, etc.) | Nothing - standalone record |
| Cardinality | One value per key per resource | Many instances per definition |
| Identity | namespace + key + owner resource | type + handle |
| Primary use | Extend a resource with extra properties | Create new data entities |
| Liquid access | resource.metafields.namespace.key | metaobjects["type"].handle or list |
| GraphQL | metafield(namespace, key) on the resource | metaobjects(type:) query |
Product reviews are a textbook Metaobject use case - FiveOh Reviews on Metaobjects uses Shopify's standard shopify--product-review definition so your data is portable and queryable.
Get more information →4. Field types: what data can they hold?
Both Metafields and Metaobject fields share the same underlying type system. Shopify supports a wide range of field types, including:
single_line_text_field,multi_line_text_fieldinteger,decimalbooleandate,date_timeurl,json,color,rating,dimensionfile_reference(images, video, generic files)- Reference types:
product_reference,collection_reference,metaobject_reference - List variants:
list.product_reference,list.metaobject_reference, etc.
The metaobject_reference type is particularly powerful: a Metafield of this type on a product can point to one or many Metaobject instances - which is exactly how a product's list of reviews is modelled.
5. Accessing both in Liquid
Accessing a Metafield
{% comment %} A text Metafield on a product {% endcomment %}
{{ product.metafields.my_namespace.care_instructions.value }}
{% comment %} A rating Metafield {% endcomment %}
{{ product.metafields.reviews.rating.value | round: 1 }}Accessing a Metaobject by handle
{% comment %} Access a single Metaobject instance by its handle {% endcomment %}
{% assign team_member = metaobjects["team_member"]["jane-smith"] %}
{{ team_member.fields.name.value }}
{{ team_member.fields.role.value }}Accessing Metaobjects via a Metafield reference on a product
{% comment %}
product.metafields.reviews.product_reviews is a
list.metaobject_reference Metafield - it returns
a list of shopify--product-review Metaobject instances.
{% endcomment %}
{% assign reviews = product.metafields.reviews.product_reviews.value %}
{% for review in reviews %}
<p>{{ review.fields.author.value }} - {{ review.fields.rating.value }}/5</p>
<p>{{ review.fields.body.value }}</p>
{% endfor %}See the Liquid metaobject object documentation for the full reference.
6. Accessing both via GraphQL
Querying a product Metafield
query {
product(id: "gid://shopify/Product/123") {
metafield(namespace: "reviews", key: "rating") {
value
type
}
}
}Querying Metaobjects by type
query {
metaobjects(type: "shopify--product-review", first: 20) {
edges {
node {
handle
fields {
key
value
}
}
}
}
}Both queries work on the Admin GraphQL API and the Storefront GraphQL API (the Storefront API requires the fields to be marked as storefront-accessible in the definition).
FiveOh Reviews on Metaobjects writes reviews as standard Shopify Metaobjects - query them with GraphQL, render them in Liquid, or export them any time you want.
Get more information →7. When to use which
A practical decision guide:
- Use a Metafield when you need to add one (or a short list) of extra properties to an existing Shopify resource - a product, variant, customer, order, etc. Examples: care label, sizing guide URL, custom badge text, loyalty points balance.
- Use a Metaobject when you need to create records of a new type that exist independently, can have many instances, and may reference other resources. Examples: product reviews, team bios, testimonials, FAQs, store locations.
- Use both together when you need to link Metaobject instances back to a resource. A product Metafield of type
list.metaobject_referencecreates the join between "this product" and "these review Metaobject records".
8. Example: product reviews use both
Shopify's standard product review system is the best illustration of both working together:
- Each individual review is a Metaobject of type
shopify--product-review, with fields for rating, body, author, date, and a product reference. - The aggregate rating (average stars) is a Metafield of type
ratingatproduct.metafields.reviews.rating- a summary value stored directly on the product for fast access. - The review count is another Metafield at
product.metafields.reviews.rating_count. - The list of all reviews for a product is a Metafield of type
list.metaobject_referenceatproduct.metafields.reviews.product_reviews, which is a list of references to individual review Metaobject instances.
This design is efficient: the aggregate Metafields give fast access to summary data (for display in product listings), while the Metaobject list gives access to the full review content (for display on the product page).
Written by Marius Korbmacher
Lead Developer at FiveOh Reviews on Metaobjects
FiveOh Reviews on Metaobjects
Reviews stored in Shopify. Rendered in Liquid. Yours to keep.
The review app that writes to Shopify's standard product review Metaobjects - server-side rendering, no JavaScript widget, no external dependency, no vendor lock-in.