# Shopify metaobjects Storefront API for Horizon themes

PUBLIC_READ access, Liquid metaobjects, theme templates and Storefront API queries for reusable store content.

- Date: 2026-10-04
- Category: Shopify

## Table of contents

- Why the Shopify metaobjects Storefront API matters now
- How Shopify metaobjects Storefront API access works
- Production checklist for Shopify metaobjects Storefront API rollout
- What breaks when Shopify metaobjects Storefront API access is wrong
- How I measure Shopify metaobjects Storefront API content on live stores
- Related work on this site
- FAQ
  - Do I need the Shopify metaobjects Storefront API if I only use Liquid themes?
  - How does the Shopify metaobjects Storefront API differ from metafields on products?
  - Can draft metaobjects appear through the Shopify metaobjects Storefront API?
  - What Storefront API scope do I need for Shopify metaobjects Storefront API queries?

Shopify metaobjects Storefront API access is the gate between reusable content in admin and what buyers actually see on a Horizon theme or a headless storefront. I am Alan Vo, a Gold Coast web developer with 18 years of shipping catalogues. Metaobjects are how I stop copying the same size chart, care block, or designer bio into fifty product metafields.

This note is for 2026 production work on Shopify Online Store and custom storefronts. It is not a repeat of basic metafield tutorials. Metafields attach one value to a product or collection. Metaobjects are standalone entries with their own fields, handles, and optional URLs. You reference them from products, sections, or GraphQL. If the definition still has storefront access set to none, Liquid returns nil and the Storefront API will not list the type.

## Why the Shopify metaobjects Storefront API matters now

The Shopify metaobjects Storefront API matters because merchandising teams finally model structured content once and reuse it everywhere. A size chart is not a rich text metafield on every SKU. It is one metaobject entry linked from twenty products. A designer profile is not pasted into collection copy. It is a metaobject the editorial team can publish or draft without redeploying theme code.

Shopify's [about metaobjects](https://shopify.dev/docs/apps/build/custom-data/metaobjects) doc draws the line clearly. Metafields extend existing resources. Metaobjects are new types with multiple related fields. App-owned definitions use the reserved `$app` prefix and TOML in `shopify.app.toml`. Merchant-owned types use a custom prefix such as `size_chart` and are created in GraphQL Admin. Both can expose storefront data, but only when you set access on the definition.

Horizon and Online Store 2.0 sections also expect dynamic sources. When a section setting can point at a metaobject field, merchants edit content in admin instead of opening JSON templates. That only works if entries are active and storefront-readable. I treat metaobject permissions as part of the launch checklist, same as canonicals on a product template.

Headless and Hydrogen teams hit the same gate from the API side. The Storefront API `metaobjects` query requires the `unauthenticated_read_metaobjects` scope and a type argument. Shopify documents that in the [metaobjects query reference](https://shopify.dev/docs/api/storefront/latest/queries/metaobjects). Without `PUBLIC_READ` on the definition, the query returns an empty connection even though admin shows entries. That mismatch wastes a day if nobody checked permissions first.

## How Shopify metaobjects Storefront API access works

Shopify metaobjects Storefront API access is controlled on the metaobject definition, not on individual entries. The Admin GraphQL enum [MetaobjectStorefrontAccess](https://shopify.dev/docs/api/admin-graphql/latest/enums/MetaobjectStorefrontAccess) has two values: `NONE` and `PUBLIC_READ`. TOML configs mirror that with `access.storefront = "none"` or `"public_read"`. Default is none. That is safer for internal app config. It is wrong for buyer-facing size charts.

![Shopify metaobjects Storefront API on a laptop showing a Shopify storefront layout](../../images/blog/shopify-metaobjects-storefront-api-1.jpg)

Liquid on Online Store themes uses a parallel path. Shopify's [metaobject Liquid object](https://shopify.dev/docs/api/liquid/objects/metaobject) explains the access pattern: `metaobjects.type.handle`, then field keys such as `metaobjects.size_chart.medium.chest_inches.value`. File reference fields expose `.value` for the drop. Rich text fields need the filter that matches their type. If you skip `.value` on a file field, you get an object where you expected a URL.

Capabilities sit on top of access. Shopify's [use metaobject capabilities](https://shopify.dev/docs/apps/build/metaobjects/use-metaobject-capabilities) guide lists four optional features. `publishable` gives draft and active states. When publishable is on, Liquid only returns active entries. Draft entries behave like missing data. `translatable` hooks into Shopify translation APIs. `renderable` exposes SEO fields and includes entries in sitemap output for Liquid storefronts. `onlineStore` assigns a theme template and a public URL, often under `/pages/content/{handle}` when you set a url handle of `content`.

Theme templates for metaobjects live under `templates/metaobject/{type}.json` as described in [metaobject theme templates](https://shopify.dev/docs/storefronts/themes/architecture/templates/metaobject). The first template becomes the default for every entry of that type. Merchants still add sections in the theme editor. An empty template file means a blank public page. I ship at least a hero and a rich text block wired to `metaobject` fields before I enable `onlineStore`.

Storefront API consumers fetch lists with `metaobjects(type: "size_chart", first: 20)` or a single row with the `metaobject` query and a handle plus type. Sort keys are documented as `id` and `updated_at`. Pagination uses standard cursor arguments. Headless components can also use Storefront Web Components with a public token, but the permission story is the same: token plus storefront access on the definition.

References connect metaobjects back to catalogue objects. A product metafield of type `metaobject_reference` or `list.metaobject_reference` points at one or many entries. In Liquid on a product template, you traverse `product.metafields.namespace.key.value` and then read fields on the referenced metaobject. On Horizon, I prefer references over duplicating handles in section settings so PIM updates stay single-source.

App-owned metaobjects can appear in Shopify Functions input queries when the type uses the `$app` prefix. Merchant-owned types do not qualify. That is fine for discounts driven by app config. It is not how you load a merchant size chart inside a function. Keep app-owned entries for machine-readable rules and merchant-owned entries for copy blocks buyers read.

![Clothing rails in a shop used as a live catalogue for Shopify metaobjects Storefront API](../../images/blog/shopify-metaobjects-storefront-api-2.jpg)

## Production checklist for Shopify metaobjects Storefront API rollout

The production checklist starts with data modeling, then permissions, then theme wiring, then SEO and measurement.

1. Name the type and fields before you create fifty entries. Changing field keys later breaks Liquid and reference metafields.
2. Decide app-owned versus merchant-owned. Apps deploy TOML. Merchants and integrators use GraphQL for merchant-owned definitions.
3. Set `access.storefront` to `PUBLIC_READ` on any type that Liquid or Storefront API must read. Leave `NONE` on internal app config types.
4. Enable `publishable` if editors need draft mode. Train them that draft means absent on the storefront, not a hidden preview URL.
5. Enable `renderable` when entries need meta titles and descriptions in sitemap output.
6. Enable `onlineStore` only when the entry is its own landing page. Ship `templates/metaobject/{type}.json` before flipping the capability on.
7. Create entries with stable handles. PIM jobs should store handle plus GID, not only display names.
8. Link products through reference metafields or section dynamic sources. Avoid hard-coded handles in theme JSON unless the handle is truly global.
9. For Hydrogen or custom storefronts, confirm the Storefront API token includes `unauthenticated_read_metaobjects` and test the type query in GraphiQL.
10. For combined colour catalogues, keep size charts on metaobjects referenced from each child product so you do not paste HTML into every variant description.
11. Document which metaobject types headless clients cache. Updated_at sorting helps incremental sync.
12. After migration, search theme code for old snippet names. Leftover includes look like missing content when metaobjects are nil.

## What breaks when Shopify metaobjects Storefront API access is wrong

Wrong storefront access is the first break. Admin shows entries. Liquid prints blank. Developers assume the theme is broken when the definition is still `NONE`. Fix the definition access, redeploy the app if TOML-owned, and hard refresh. No theme change required.

Draft publishable entries are the second break. Merchandisers save a new size chart as draft and ask why the PDP still shows the old chart. Shopify's Liquid note is explicit: draft metaobjects return nil. Either activate the entry or turn off publishable if you do not want that workflow.

Missing onlineStore templates are the third break. Capabilities create URLs under `/pages/content/...` but the default template is empty. Buyers see a shell page. Merchants blame SEO. Add sections or disable onlineStore until the template exists.

![Theme code on a monitor during Shopify metaobjects Storefront API work](../../images/blog/shopify-metaobjects-storefront-api-3.jpg)

Reference metafields pointing at deleted entries are the fourth break. Liquid does not throw. It returns empty. QA must include orphan references after catalogue cleanups.

Headless caches are the fifth break. A CDN or client cache still serves yesterday's metaobject list after a copy change. Use `updated_at` in sync jobs or shorten cache TTL on content types that marketing edits weekly.

Over-modeling is the sixth break. Not every repeating field needs a metaobject. A single global banner might be a shop metafield. Metaobjects shine when the same shape repeats with different values and references. If you create forty types, editors lose the plot in admin search.

## How I measure Shopify metaobjects Storefront API content on live stores

I measure metaobject rollouts on coverage, render truth, SEO surface, and editor time. Coverage first. For each product type that should show a size chart or care block, does the reference metafield resolve in Liquid on a sampled SKU? I script a theme preview URL list rather than clicking hundreds of admin rows.

Render truth second. Compare admin field values to PDP output for file references and rich text. Metaobject file fields often need `.value` and an image filter. Missing filters look like broken images in Lighthouse, not like admin errors.

SEO third. When `renderable` is on, fetch sitemap entries or use Search Console URL inspection on one metaobject URL. Titles should come from metaobject SEO fields, not from a duplicate page in Pages. If both exist, pick one indexable URL.

Editor time fourth. Merchants should update one entry and see it propagate to every linked product. If they still open product descriptions to paste HTML, the reference wiring failed.

I do not invent conversion lift from metaobjects alone. The published storefront numbers I cite stay on case studies such as [Their Nibs](https://alanvo.com/work/their-nibs/), where a rebuild delivered 31% more conversions and 48% more orders. Metaobjects reduce copy drift and speed up launches. They are infrastructure, not a magic metric.

## Related work on this site

Structured catalogue content shows up on every jewellery and home storefront I ship. The [Tamannaah Fine Jewellery Shopify Plus storefront](https://alanvo.com/work/tamannaah-fine-jewellery/) and [Ferm Living](https://alanvo.com/work/ferm-living/) both need reusable care and specification blocks without forking the theme on every SKU. [Their Nibs](https://alanvo.com/work/their-nibs/) is the rebuild where editorial modules had to stay fast while merchandising kept changing. For URL and schema discipline on products that reference metaobjects, read [Shopify SEO for collection and product pages](https://alanvo.com/blog/shopify-collection-product-seo/). If you are moving the theme to Horizon at the same time, pair this note with [How to migrate a Dawn store to Shopify Horizon](https://alanvo.com/blog/shopify-horizon-theme-migration/).

![Phone showing a product page in Shopify metaobjects Storefront API testing](../../images/blog/shopify-metaobjects-storefront-api-4.jpg)

## FAQ

### Do I need the Shopify metaobjects Storefront API if I only use Liquid themes?

You need storefront access on the definition even for Liquid-only themes. Liquid reads metaobjects through the same permission model as the Storefront API. Set `PUBLIC_READ` on types buyers should see. Headless queries are optional for Online Store, but the access flag is not.

### How does the Shopify metaobjects Storefront API differ from metafields on products?

Metafields attach one custom value to an existing Shopify resource. Metaobjects are standalone entries with multiple fields and their own handles. You link them with reference metafields or dynamic sources. Use metaobjects when the same structured record should appear on many products or pages.

### Can draft metaobjects appear through the Shopify metaobjects Storefront API?

No. When the publishable capability is enabled, only active entries are readable on the storefront. Draft entries return nil in Liquid and do not appear in Storefront API results for buyer-facing tokens. Activate the entry or disable publishable if you do not want that state machine.

### What Storefront API scope do I need for Shopify metaobjects Storefront API queries?

Shopify documents that the `metaobjects` query requires the `unauthenticated_read_metaobjects` access scope on the Storefront API token, plus `PUBLIC_READ` on the metaobject definition. Without both, queries return empty data even though admin lists entries.


![Card payment at a counter after a Shopify metaobjects Storefront API release](../../images/blog/shopify-metaobjects-storefront-api-5.jpg)


HTML version: https://alanvo.com/blog/shopify-metaobjects-storefront-api/