Guide · Shared metafields

Metafields

BigCommerce metafields are a namespace, a key and a string. Nothing more. This is how Ottermerce gives them a type, a list, a set of options and a place on your storefront — and what it deliberately does not pretend to do.

Why define anything

Adding the same three metafields to four hundred products by hand is where typos come from. Define them once and every product gets the same fields, in the same order, with the right input and the same validation — and a CSV import is checked against them too.

Defining a field changes nothing in your store on its own. It changes what the editor draws and what it will accept.

The options

Content types

Read-only and Use on storefront are one BigCommerce setting

These two tick-boxes are not app-level flags. Together they set the metafield's permission_set, which is a real BigCommerce field:

The *_sf_access pair is what makes a metafield visible to the Storefront GraphQL API. Without it, a theme querying the field gets an empty result and no error at all.

Filling them in

Open a product from the Catalog and go to the Metafields tab. It has two parts:

• Shared fields — one input per definition, in the order you arranged them, with the description as help text and the flags shown on the label.
• Custom metafields — anything on this product that no definition describes. No type, no validation; exactly as before.

A field another metafields app defined

BigCommerce has no idea of a "shared" field. It stores a namespace, a key and a string — that is the whole record. So the schema behind a shared field lives in whichever app defined it, and only the value is written to BigCommerce.

That means a field you set up as shared in another metafields app arrives here undescribed, on the Custom metafields tab. It is not a fault and there is nothing to import: probed on a live store, the places a schema might hide — channel metafields, brand metafields — are empty.

Press Make shared on the row and Ottermerce describes it on this store instead, guessing the content type from the value already stored (#e22929 becomes Color, ["80","81"] a list of numbers). The guess is named when it is made, and changing it later is two clicks — a value that no longer fits its type is shown rather than hidden, and removing a definition never touches the values.

Both submit together as one set — one Save covers both tabs — because BigCommerce metafields are written as a REPLACE: sending only the shared ones would delete the ad-hoc ones. If the store has gained a metafield the tab never showed, it is kept as-is and the summary says so, rather than being deleted or the save being refused.

Custom fields are a different BigCommerce concept — a name and a value, shown by most themes with no work — and have their own tab. Nothing on the Metafields tab touches them.

Filling one field across the catalog

One product at a time is the wrong tool for a care label that four hundred products need. Fill fields is the same field seen the other way round: pick a definition, filter the catalog, and every matching product gets a row with that one field in it.

The empty cells are the point. A product with no value still gets a row, so the screen answers "which products are missing this" rather than "which products already have it", and the header counts how many of the page are filled in.

• Fill… sets every row on the page, or just the ticked ones, to one value. It fills the cells and leaves them pending, so you read the table before anything is written — that review step is the whole difference between this and a bulk endpoint.
• Preview is a real dry run through the importer. Save writes one file, and it lands in History like any other import.
• Clearing a cell removes the metafield from that product. Setting one adds or updates it.

A save covers up to 100 products, which is one page of the grid at its largest, and it counts against your plan's daily import allowance the same way a bulk edit does. Beyond that, export the catalog, fill the column in a spreadsheet and import it back.

Products, variants, categories and brands

A shared field is defined on something. Switch between Products, Variants, Categories and Brands at the top of the Metafields page, and the grid follows whichever definition you pick.

Variants are where this saves the most work: a note per size, a fabric code per colour, across every variant in the catalog. The grid still pages by product, so a product's variants stay together and the header counts both. A product with no SKU cannot be edited here, because a variant is attached to its parent by SKU in the file — those rows are shown but locked, and say so.

Brands are the simplest: a row is a brand and its value, with a name search to narrow the list.

Categories work the same way with one difference worth knowing: a category is named in a file by its full path, not by its id alone. So a category whose own name contains a / cannot be edited here, because the path would then mean something else — "Sale/Clearance" reads as two levels. Those rows are shown but locked, and say so. Rename the category in BigCommerce and it becomes editable.

A field marked read-only cannot be filled in here. The cells are shown but not editable, and a save is refused rather than quietly ignored — change the definition first if you meant to edit it.

Reading them on the storefront

Ticking Use on storefront is half the job; the theme still has to ask for the field by namespace and key, and getting either wrong returns an empty list silently. So the Metafields screen writes the query for you, including the Stencil front matter with its quoting already escaped.

Paste it at the top of a template. BigCommerce resolves it server-side and exposes the response as gql, so no client-side request is needed:

{{#each gql.data.site.product.metafields.edges}}
    {{#if node.key '===' "care_instructions"}}
        {{{node.value}}}
    {{/if}}
{{/each}}

Triple braces for anything holding markup — with two, the HTML is escaped and the shopper sees the tags.

If your fields span more than one namespace, the generated query aliases each selection (ns0:, ns1:) because GraphQL rejects the same field selected twice without one.

In a CSV

The same visibility travels in a spreadsheet, so a bulk import can set it too:

One permission column per field, because the whole point is that fields differ — Metafield Command already occupies the one-per-row shape. Leave the column out and a create gets write_and_sf_access while an update leaves the existing visibility alone. An unrecognised value produces a warning on the row and the default is used, rather than failing every other metafield on that product.

What this does not do

Said plainly, because the gaps matter more than the features:

• Products only, for now. BigCommerce also has metafields on variants, categories, brands, channels and orders. The definitions table is keyed by resource, so adding one is a small change — plus an editor to fill it in. That second half is the reason it is not offered yet: a definition for a resource with no editor behind it is a dead end, where you define a field and then find nowhere to type into it.
• No file type, and no upload. This app hosts nothing. A link to a file you already host is a URL, which is what it is — a separate "file" type would only invite you to look for an upload button that does not exist.
• No rich-text WYSIWYG. A rich text field is a plain textarea holding HTML. It is honest about that rather than shipping an editor that mangles markup.
• Deleting a definition never deletes data. The values stay on their products and go back to being shown as custom metafields.