Alan Vo

Available for remote roles

Menu
  1. Home
  2. Blog
  3. Shopify
  4. Shopify metaobjects Storefront API for Horizon themes

Shopify

Shopify metaobjects Storefront API for Horizon themes

Shopify

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 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. 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 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

Liquid on Online Store themes uses a parallel path. Shopify's metaobject Liquid object 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 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. 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

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

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, 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.

Structured catalogue content shows up on every jewellery and home storefront I ship. The Tamannaah Fine Jewellery Shopify Plus storefront and Ferm Living both need reusable care and specification blocks without forking the theme on every SKU. 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. 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.

Phone showing a product page in Shopify metaobjects Storefront API testing

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

Keep reading

Contact if you want this kind of work on a live store.