Shopify Metafields vs. Metaobjects: what's the difference?

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.

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.

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_field
• integer, decimal
• boolean
• date, date_time
• url, json, color, rating, dimension
• file_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.

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: "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).

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 product_review, with fields for rating, body, author, date, and a product reference.
• The aggregate rating (average stars) is a Metafield of type rating at product.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_reference at product.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