Inline Metafields

Set up your fields

Open the app from Apps → My Apps → Inline Metafields and choose the Fields tab. As an example, here is how to add a dropdown called Materials with three choices:

1. Click Add field.
2. For Label, enter Materials. This is the name you’ll see on each product. The Key fills in as materials; it’s the name your theme uses to find the value and the column name in a CSV file.
3. For Type, choose Dropdown.
4. Under Options, enter one choice per line: Leather, Vinyl and Plastic. They appear in this order.
5. Optionally, add Help text, such as “What the outer shell is made of”. It’s shown under the field on every product.
6. Leave Show on storefront on (see below), and click Add field.

Each type has its own input on the product, and its own rules:

A value that breaks a field’s rules is refused with a message saying why, so a typo such as “Leathr” can’t be saved.

• A field’s key and type can’t be changed after you add it. Everything else can: click Edit next to the field. To change the type, delete the field and add it again with the same key.
• Changing a field never changes products that already have a value. If you rename or remove the option “Vinyl”, products set to Vinyl keep it, and the product shows a warning until someone picks a new value.
• Deleting a field doesn’t delete the values already saved on products. They stay on the product and move to the Custom metafields section.
• Applies to sets whether a field has one value per product (the default) or one value per variant, such as a swatch color for each size and color. Like the key and type, it can’t be changed after you add the field.
• Use Move up and Move down to set the order fields appear in on each product and in a CSV file.
• You can add up to 100 fields, each dropdown or multi-select with up to 100 options.

Show on storefront. New fields are on by default, so your theme or headless storefront can read them, and so can anyone visiting your store. For internal details, such as supplier codes or cost notes, turn Show on storefront off to keep the field private. To show fields to shoppers, drag the Product Fields widget onto your product page in Page Builder, with no theme code; see Showing your fields on the storefront.

Fill in fields on a product

You can open a product’s fields from three places. They all show the same editor.

From the product list.

1. Go to Products → View.
2. On the product’s row, open the Action menu (···) and choose Inline Metafields.
3. The editor opens in a panel over the list, so you don’t lose your place.

While you’re editing a product.

1. Open the product from Products → View.
2. In the Description section, open the Action menu and choose Inline Metafields.
3. The editor opens in a panel over the product page. Close it to carry on editing the product.

On a new product, save the product first. Fields are saved on a product, so there is nothing to attach them to until it exists.

From the app.

1. Open Inline Metafields from Apps → My Apps and choose the Products tab.
2. Search by name, SKU or brand, and click Edit fields on a product.
3. Click ← All products to go back to your search.

In the editor:

• Your fields are listed first, under Fields. For Materials, pick Leather from the list, then click Save fields. You can change several fields and save them together.
• To remove a value, set the field back to Not set (or empty a text field) and click Save fields.
• If a saved value no longer fits the field, for example after you removed an option, you’ll see Saved value doesn’t match this field. The value stays as it is until you choose a new one or click Clear saved value.
• For a media link, paste a link: BigCommerce doesn’t let apps upload files, so Inline Metafields can’t take one directly. For an image, copy its link from BigCommerce’s Image Manager; for a PDF or other file, upload it to your store with WebDAV and copy its link; for a video, use the YouTube or Vimeo page link, or a link to an .mp4 or .webm file. Images show a preview, videos play in the editor, and files show as a named link. Links must start with https://.
• For a product reference, search for a product by name, SKU or brand and click Choose (or Add, for a field that takes several). Use the arrows to change the order, and Remove to take one out.
• For rich text, use the toolbar for bold, italic, lists and links. Text pasted from another site or a document keeps only that formatting.
• Variant fields are listed after your product fields, one block per variant, such as “Size: L, Color: Red”. Click Edit on a variant, fill in its fields and click Save variant. Each block shows how many of its fields are set. On the Products tab, a variant field counts towards Fields set once every variant of the product has a value.
• Custom metafields holds one-off values that don’t need a field of their own. Click Show to see them, and Add metafield to add one with any key and value.
• Other metafields lists metafields added by your other apps and integrations. They are shown so you can see them, but can’t be changed here, so those apps keep working.

Update many products with a CSV file

To fill in or change fields on many products, export them to a CSV file, edit it in a spreadsheet, and import it back. Open the app and choose the Import / export tab.

Export. Click Export CSV. The file has one row per product and these columns:

• product_id, sku and name: which product the row is. Leave these as they are.
• One column per field, named by its key, such as materials.
• _problems: any field whose saved value no longer fits its rules. It’s for your information and is ignored when you import.

Edit. Change the cells you want to change. When you import:

• An empty cell leaves the value as it is. You can delete the columns and rows you aren’t changing.
• To remove a value, type [clear] in the cell.
• A dropdown cell must be one of its options, such as Leather. Capitals don’t matter.
• For a multi-select, separate the choices with a vertical bar: Leather|Vinyl.
• For yes / no, use yes or no (true, false, 1 and 0 also work).
• Write dates as year-month-day: 2026-11-01. Write numbers without a thousands separator: 1200, not 1,200.
• For a link or media link, use the full link starting with https://. For a color, use hex: #1A2B3C. For a product reference, use product ids separated by a vertical bar: 123|456. Rich text can be plain text or HTML; only bold, italic, lists and links are kept.
• To add rows for other products, fill in product_id, or just sku (the product’s own SKU, not a variant’s).

Variant fields. If you have fields that apply to variants, the file also has variant_id and variant_sku columns, and each product’s row is followed by one row per variant, named like “Sample Tee — Size: S, Color: Red”. Fill in variant fields on the variant rows and product fields on the product rows. A variant row is matched by variant_sku (or variant_id for a variant with no SKU); leave its sku cell empty. To add a row for a variant, give it its variant_sku.

Save the file as CSV (UTF-8). Some spreadsheet apps change dates and long numbers when they open a CSV; the dry run below will show it if that happens.

Check, then import.

1. Click Choose CSV file, select your file, and click Check file.
2. This is a dry run: nothing is changed yet. You’ll see how many rows will change, a Changes table with each value now and after import, and an Errors table listing any cell that can’t be imported and why.
3. Fix any errors in the file and check it again, or carry on: a row with an error is skipped completely, and every other row is imported.
4. Click Import (the button says how many rows will change). When it finishes you’ll see how many rows were imported and which, if any, were skipped.

A file can have up to 10,000 rows and be up to 5 MB. Larger catalogs can be split across several files. You can stop a check or an import part way; rows already imported stay imported, and exporting again shows where things stand.

With Page Builder widgets (no theme code)

1. Go to Storefront → Themes and click Customize to open Page Builder.
2. Use the page menu at the top to open a product page, or browse to a product in the preview.
3. Under Widgets, scroll to Custom and drag Product Fields into an area on the product page, such as below the price or below the description.
4. Click the widget to choose which fields it shows, a heading, the layout and the colors. Match the product details looks like the theme’s own SKU and weight rows.
5. Click Publish.

The widget appears on every product page and shows only the fields that product has a value for. Fields that vary by option (size, color and so on) change to the shopper’s choice as they pick it. Fields you add later are shown too, unless you untick them in the widget.

Variant Table. Drag Variant Table onto the product page for a table with a row for each variant: its options, its variant fields, its price, whether it’s in stock, and an Add to cart button. Shoppers can compare every size or color at once and add the one they want. The variant they’ve picked is highlighted. Products with only one variant don’t show the table.

Widgets work on Stencil themes only. On Catalyst or another headless storefront, use the GraphQL query further down.

Removing the widgets. To take both widgets off your storefront, open the app’s Settings tab and click Remove storefront widgets. Every Product Fields and Variant Table widget comes off your pages, and both leave Page Builder until you click Turn on storefront widgets. Your fields and values aren’t affected. Turning the widgets back on doesn’t restore the ones you had placed, so place them again in Page Builder.

In your theme's code (Stencil)

This shows every field marked Show on storefront as a Label: value row under the SKU and weight. Fields you add later appear on their own, with no further theme changes. You can paste it in from the control panel: go to Storefront → Themes, open your theme’s Advanced menu and choose Edit Theme Files. A theme from the Theme Marketplace has to be copied before you can edit it.

1. Ask for the fields. Open templates/pages/product.html. The file starts with a block between two --- lines. Paste this just above the second ---, starting at the left edge like the product:line. Use spaces, not tabs, and keep the backslashes.

gql: "query InlineMetafields($productId: Int!) {
    site {
      product(entityId: $productId) {
        metafields(namespace: \"inline_metafields\", first: 50) {
          edges {
            node {
              key
              value
              description
            }
          }
        }
      }
    }
  }"

If the block already has a gql: line, don’t add a second one: add the metafields(…) { … } part inside the existing query’s product(entityId: $productId) { … }.

2. Show them. Open templates/components/products/product-view.html and find the line {{#if settings.bulk_discount_enabled}}. Paste this on a new line just above it, inside <dl class="productView-info">:

{{!-- Inline Metafields: every field marked Show on storefront --}}
{{#each gql.data.site.product.metafields.edges}}
    <dt class="productView-info-name">{{#if node.description}}{{node.description}}{{else}}{{capitalize (strReplace node.key "_" " ")}}{{/if}}:</dt>
    <dd class="productView-info-value">{{#if (isArray (JSONparseSafe node.value))}}{{#each (JSONparseSafe node.value)}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}{{else if node.value '===' 'true'}}Yes{{else if node.value '===' 'false'}}No{{else}}{{nl2br node.value}}{{/if}}</dd>
{{/each}}

Save both files and open a product that has a value. Each row’s label is the field’s Label; for a custom metafield it’s the description, or the key with underscores as spaces when there is no description. Multi-select values are listed with commas, yes/no fields show Yes or No, and dates show as 2026-10-08. Rows appear in the order BigCommerce returns them, usually the order the values were first saved.

Advanced: one block per field. To choose your own labels and order, show only some fields, or format dates, use a block per key instead of the code in step 2. This example uses the keys materials, features, dishwasher_safe, launch_date and care_notes; use your own.

{{#each gql.data.site.product.metafields.edges}}
    {{!-- Dropdown, single-line text or number --}}
    {{#if node.key '===' 'materials'}}
        <dt class="productView-info-name">Materials:</dt>
        <dd class="productView-info-value">{{node.value}}</dd>
    {{/if}}

    {{!-- Multi-select: a list, shown comma-separated --}}
    {{#if node.key '===' 'features'}}
        <dt class="productView-info-name">Features:</dt>
        <dd class="productView-info-value">
            {{#JSONparseSafe node.value}}
                {{#each this}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}
            {{else}}
                {{node.value}}
            {{/JSONparseSafe}}
        </dd>
    {{/if}}

    {{!-- Yes / no --}}
    {{#if node.key '===' 'dishwasher_safe'}}
        <dt class="productView-info-name">Dishwasher safe:</dt>
        <dd class="productView-info-value">{{#if node.value '===' 'true'}}Yes{{else}}No{{/if}}</dd>
    {{/if}}

    {{!-- Date --}}
    {{#if node.key '===' 'launch_date'}}
        <dt class="productView-info-name">Available from:</dt>
        <dd class="productView-info-value">{{moment node.value "MMMM D, YYYY"}}</dd>
    {{/if}}

    {{!-- Multi-line text, keeping line breaks --}}
    {{#if node.key '===' 'care_notes'}}
        <dt class="productView-info-name">Care:</dt>
        <dd class="productView-info-value">{{nl2br node.value}}</dd>
    {{/if}}
{{/each}}

Use double braces ({{node.value}}), not triple: values are text your staff typed, and double braces make sure they display as text.

Catalyst and other headless storefronts

Query the GraphQL Storefront API. In Catalyst, add this next to the product page’s other queries in core/app/[locale]/(default)/product/[slug]/page-data.ts and fetch it with the Catalyst client. To ask for specific fields, add keys: ["materials"] next to namespace.

query InlineMetafields($entityId: Int!) {
  site {
    product(entityId: $entityId) {
      metafields(namespace: "inline_metafields", first: 50) {
        edges {
          node {
            key
            value
          }
        }
      }
    }
  }
}

Up to 50 fields come back per request, as a list of key and value pairs. Fields with no value on the product aren’t in the list.

How each type of field is stored

Every value comes back as text, in these forms:

Variant fields are saved on each variant rather than on the product, so your theme reads them from the product’s variants.

If you change a field after values were saved, for example by removing a dropdown option, products keep their old value until someone changes it, so it can still appear on the storefront.