You're building a Shopify section that needs to behave differently for 80 different products. You could add 80 blocks to the section schema, or you could wire up metafields and let the data do the work. The architecture decision matters more than most devs realize before they've had to support a theme at scale.
Does this value need to vary per product, collection, or page?
The short answer
Section settings live in the theme's customization layer. Metafields live on the resource itself (product, variant, collection, page). When you need the same section to look or behave differently per resource, that's a metafield job.
The 30-second rule: if a merchant needs to configure something once per product rather than once per section placement, it belongs in a metafield.
Why section settings break down at scale
Shopify's section settings write to config/settings_data.json and templates/*.json. For a small store with a handful of products, this works fine. At 100+ products with per-product overrides, the customization file grows into something no one wants to debug.
The practical problem: every time a merchant wants a product-specific headline, accent color, or media swap inside a section, they have to either (a) duplicate the section block, or (b) use conditional logic you've pre-baked into the schema. Both approaches have ceilings.
Duplicate blocks compound fast. A hero section with 40 product-specific blocks is both a maintenance problem and a theme editor performance problem. Conditional schema logic (showing/hiding settings based on a dropdown selection) is clever until the conditions multiply and the schema becomes 300 lines of JSON that nobody remembers.
The case for metafield-driven architecture
The cleaner model: one section block with sensible defaults, and a metafield lookup that overrides those defaults per resource. The section stays thin. The product owns its data. The merchant manages product content in the product admin, not the theme editor.
I first shipped this pattern on a DTC brand build in Q4 2025. The theme needed four section layouts (columns, scroll, collapsible, slider), each capable of pulling per-product media and copy overrides. Building that as theme customization blocks would have been messy. Wiring it to product metafields kept the section schema clean and put content ownership where it belonged.
How metafield-driven Liquid sections actually work
The Liquid syntax is straightforward once you've done it once.
{% liquid
assign section_headline = section.settings.headline
if product.metafields.custom.section_headline != blank
assign section_headline = product.metafields.custom.section_headline
endif
%}
<h2>{{ section_headline }}</h2>
Three lines of Liquid, and the section now respects per-product copy without requiring any theme editor interaction after initial setup.
The fallback chain is the important part. You want:
“The metafield wins when it's set. The section setting covers anything the metafield leaves blank. The hardcoded fallback catches edge cases.”
- Metafield value (if set on this product)
- Section setting (the merchant-configured default)
- Hardcoded fallback (your design default)
This gives you three layers of control without any of them conflicting.
Namespace and key conventions
Pick a namespace and stay consistent. custom is Shopify's default namespace for merchant-defined metafields and shows up in the admin without any extra configuration. For programmatically created metafields (via Admin API or metafield definitions), use a more specific namespace like theme or content to separate your schema from merchant additions.
Key naming: use snake_case, be specific, avoid abbreviations. hero_background_color beats hero_bg in a codebase someone else has to read six months later.
Should you use metafields for this section?
The decision tree is not complicated, but it's easy to guess wrong the first time.
What metafields can't do
Storefront API access is gated. By default, metafields are not exposed to the Storefront API. You have to explicitly set storefront access on each metafield definition if you need it for headless builds or custom storefronts. Liquid templates access metafields server-side, so this doesn't affect standard Liquid usage, but it matters for any client-side JavaScript or headless layer.
The theme editor experience has gaps. Metafields you define via the Admin API don't automatically surface as nice picker fields in the Customize panel. Shopify's dynamic sources feature helps, but it requires metafield definitions with the right type and explicit "access" settings. If your merchant audience lives in the Customize panel, plan the definition setup before you ship the section.
Validation types matter more than you think. Shopify's metafield type system (single_line_text_field, color, file_reference, product_reference, json, etc.) affects what the Admin UI shows and what validation runs. A color type gives merchants a color picker. A single_line_text_field gives them a text input. Get the type wrong and you'll have merchants entering hex codes into text fields and wondering why the picker doesn't show up.
Related questions
If you're building the full theme architecture, the DTC Theme Starter ships with this pattern pre-built: metafield-driven sections, Core Web Vitals tuned, and Meta CAPI server-side already wired.
The production implementation I referenced above is documented in the theme build case study, which covers the cross-browser video problem that ran alongside the metafield architecture work.
If you're interested in automating Shopify page creation beyond section architecture, the AI page generator case study covers the CLI build that generates full production pages from text prompts.
What's the difference between metafields and section settings in Shopify?
Section settings are stored in the theme's JSON customization files and apply to a section placement. Metafields are stored on a Shopify resource (product, collection, page, variant) and travel with that resource regardless of where it appears. If you need the same data in multiple places or per-resource overrides, use metafields. If you need theme-level configuration, use section settings.
Can I use metafields in Shopify Liquid sections without the Admin API?
Yes. Merchants can create metafields manually in the Shopify admin (Metafields section on each product, collection, or page). You access them in Liquid with resource.metafields.namespace.key. If you want type validation, required fields, or programmatic creation at scale, you'll need the Admin API, but the Liquid access works regardless of how the metafield was created.
How do I set up Shopify metafield definitions for a theme?
Create definitions in Settings > Custom data in the Shopify admin, or via the Admin API's MetafieldDefinition mutations. Set the owner type (product, collection, etc.), namespace, key, and type. Once a definition exists, Shopify validates all values against it and shows the appropriate input in the admin. For theme use, set "storefront access" if you need the data in a headless layer.
Should I use metafields or content entries for theme copy?
Metafields on existing resources (products, collections) work well for product-specific overrides. Shopify's metaobjects (formerly "custom content") work better for standalone content types that don't map to a Shopify resource. If you need a custom testimonial object that appears across the site, a metaobject is cleaner. If you need a product headline to vary per product, a product metafield is the right fit.
What happens if a metafield isn't set for a product?
The Liquid value returns blank (empty string). Your fallback chain handles this: check if the metafield is blank, fall through to the section setting, fall through to your hardcoded default. Never assume a metafield will be set for every resource. Blank checks are required.
Are there performance implications to metafield reads in Liquid?
No meaningful ones. Shopify loads metafields within the same server-side render pass as the rest of the Liquid context. Unlike the Storefront API, there's no extra HTTP round-trip. The only consideration is that metafield namespaces you want in Liquid need to be declared in the theme's settings_schema.json under "metafields" if you're using the theme namespace. The custom namespace is available by default.
Sources and specifics
- The fallback chain pattern (metafield > section setting > hardcoded default) was validated in a DTC brand theme build in Q4 2025 covering four section layout variants.
- Shopify's metafield type system expanded significantly in 2022-2024, adding file_reference, product_reference, color, and json types with admin validation UI.
- The Shopify 2.0 section architecture (online store 2.0) stabilized in 2021 with the introduction of JSON templates and section groups.
- Storefront API metafield access requires explicit
storefrontgrant on each metafield definition; this is not enabled by default. - All Liquid examples in this article were tested against Shopify's Dawn theme architecture (Liquid 5+, Shopify CLI 3+).