Getting enriched product data onto BigCommerce product pages

Enriching a product record is only half the job — a spec, use-case, or identifier only earns its keep once it's actually rendered on the product detail page (PDP) where a shopper or an AI shopping agent can read it. On BigCommerce, that means understanding two different data containers (custom fields and metafields), how BigCommerce's Stencil templating layer binds each one to the theme, and what actually lands in the HTML a browser or crawler receives. This guide walks through both paths with working examples from BigCommerce's Cornerstone theme.

Where the enriched attribute actually lives

BigCommerce gives you two native places to store an enriched attribute before it ever touches a template:

Custom fields — simple name/value pairs attached to a product record, editable in the admin under a product's Custom Fields tab, or via the REST Catalog API:

POST /v3/catalog/products/:product_id/custom-fields

Each name and value is capped at 250 characters, and BigCommerce enforces a per-product custom field limit, so they're best for short public-facing attributes (grade, certification, capacity) rather than long-form content.

Metafields — a more flexible key/value store (up to 65,535 characters per value) reached via:

POST /v3/catalog/products/:product_id/metafields

requiring namespace, key, value, and a permission_set. This last field matters a lot for page rendering: a metafield is only visible to the storefront GraphQL API if permission_set is read_and_sf_access or write_and_sf_access. Set it to read, write, or app_only and the field will save fine in the admin but never reach the page — a common cause of "why isn't my enriched attribute showing up" tickets.

How that data binds to the theme

BigCommerce's storefront rendering layer is Stencil: Handlebars templates under templates/pages/ (page-level) and templates/components/ (partials), fed by a JSON context object BigCommerce assembles per request.

Custom fields ride along with the rest of the product context automatically — no extra query needed. They arrive as product.custom_fields, an array of objects each carrying a name and a value, available to any component in the render tree.

Metafields are not included in the default product context. To pull one into a page, you add a GraphQL Storefront API query to the front matter (a YAML block at the top of the file) of a top-level page template — critically, only files directly under templates/pages/ support front matter; you cannot add a gql query to a component or partial, and the whole front-matter block is capped at 64KB. The query result lands in the page context under the gql key, and BigCommerce injects a $productId variable automatically on product pages so the query can be product-scoped.

Concrete example: a custom field, already wired up

Cornerstone (BigCommerce's reference theme) ships this partial at templates/components/products/custom-fields.html:

{{#each product.custom_fields}}
<dt class="productView-info-name">{{name}}:</dt>
<dd class="productView-info-value">{{{value}}}</dd>
{{/each}}

It's included from product-view.html inside the product info list container, gated by a theme setting:

{{#if theme_settings.show_custom_fields_tabs '!==' true}}
    {{> components/products/custom-fields }}
{{/if}}

So if a PIM-driven enrichment pipeline writes a custom field named Material with value 316 stainless steel to a product, it appears in the rendered HTML with zero template changes — Cornerstone (and most Stencil themes derived from it) already loops over every custom field on the product.

Concrete example: a metafield, pulled in explicitly

To surface a richer attribute stored as a metafield — say a size-guide entry in a shared namespace — add a gql block to the front matter of templates/pages/product.html:

---
gql: "query productById($productId: Int!) {
  site {
    product(entityId: $productId) {
      metafields(namespace: \"shared\", keys: [\"size-guide\"]) {
        edges {
          node {
            key
            value
          }
        }
      }
    }
  }
}"
---

Then reference it anywhere in that template (or pass it to a component as a Handlebars argument, since the query itself can't live in the component):

{{#each gql.data.site.product.metafields.edges}}
  {{#if node.key '===' 'size-guide'}}
    <div class="productView-sizeGuide">{{{node.value}}}</div>
  {{/if}}
{{/each}}

Double quotes inside the GraphQL string must be escaped (\"). Field and argument names on the metafields connection can shift slightly between API versions, so BigCommerce's Storefront API Playground (Settings → API → Storefront API Playground in the admin) is the fastest way to confirm the exact query shape before pasting it into front matter.

Making the attribute legible to AI agents, not just shoppers

A visible name/value pair in the details list helps a human but isn't structured data. Cornerstone already emits Product JSON-LD from templates/components/products/schema.html, covering name, sku, mpn, gtin, brand, offers, and reviews — but it does not automatically include custom fields or metafields. If an enriched attribute is decision-relevant (material, certification, compatible use), add it as a schema.org additionalProperty in that same script block:

"additionalProperty": [
  {{#each product.custom_fields}}
  {
    "@type": "PropertyValue",
    "name": {{{JSONstringify name}}},
    "value": {{{JSONstringify value}}}
  }{{#unless @last}},{{/unless}}
  {{/each}}
]

That one addition means the same enriched attribute is present three ways: in the visible DOM, in view-source, and in machine-readable JSON-LD that AI shopping agents and search crawlers parse directly.

How to validate

• View-source vs. rendered DOM: Stencil renders Handlebars server-side, so a custom field or a front-matter-driven metafield should already be present in view-source: on the live page — not injected later by client-side JavaScript. If it only shows up in the browser's Elements panel (rendered DOM) but not in view-source, something client-side is adding it, which most crawlers and simpler AI agents won't see.
• curl check:

curl -s https://yourstore.com/product-path/ | grep -i "your-field-name"

should return the name/value markup or JSON-LD line directly from the HTML response, confirming server-side rendering rather than a client hydration artifact.

• JSON-LD validation: run the page through Google's Rich Results Test or the Schema Markup Validator to confirm the additionalProperty entries parse as valid PropertyValue nodes attached to the Product type.
• GraphQL sanity check: before trusting a metafield-driven section, run the same query in the Storefront API Playground to confirm the permission_set actually returns data — a null or empty edges array there usually means the metafield's permission isn't set to a storefront-accessible value.

Verified as of July 2026

Mechanisms described here — custom fields, metafields with permission_set, Stencil front matter gql blocks, and Cornerstone's default template structure — reflect BigCommerce's current Stencil/GraphQL Storefront API documentation and the public Cornerstone theme repository as of July 2026. Exact behavior (character limits, per-product field caps, theme partial names) can vary by BigCommerce plan and by how far a theme has diverged from Cornerstone, so confirm against the live theme's files before shipping.

Anglera sits upstream of all of this: it continuously enriches the underlying product record — filling in the custom field or metafield value itself, at scale, across a catalog — so the template work above has complete, accurate data to render rather than blank fields. It plugs into BigCommerce (or whatever PIM or commerce platform holds the record of truth) without requiring a replatform; your PIM stores the data, Anglera does the work of keeping it complete.