What are BigCommerce custom fields?

When you edit a product in BigCommerce, below the price and the images there is a section called Custom fields: a list of name-and-value pairs you fill in by hand. "Fabric: washed linen." "Fit: straight." They are not purchase options or product variants, because the customer chooses nothing with them, and they are not Shopify's metafields either, although the two are often compared. They are the spec sheet the platform lets you write without touching the theme. They matter to you because that is where the product attributes that both your customers and search engines look for tend to end up, and because data being on the product does not mean it is on the page.

How it works

BigCommerce's help center presents them as additional product information that appears on the product page, with examples like a book's ISBN, a movie's release date or a wine's vintage. They display as name-and-value pairs, separate from the description, and show up on their own in the product details if they are defined. Exactly where depends on the theme: some give them a tab of their own.⁠^{[1]BigCommerce, help center. Custom Fields}

There are three ways to create them: in the control panel, from the product page, in the Custom fields section; in bulk, by importing a CSV; or through the API.⁠^{[1]BigCommerce, help center. Custom Fields} The Catalog API creates them with a POST request to /v3/catalog/products/{product_id}/custom-fields, and its rules are these:⁠^{[2]BigCommerce API Reference. Create Product Custom Field}

• Two required fields, name and value. Both show up in the store, in orders and elsewhere, according to the reference itself.
• Each name-value pair must be unique within the product.
• At most 200 custom fields per product and 250 characters per field.

The help center says 255 characters per field.⁠^{[1]BigCommerce, help center. Custom Fields} BigCommerce's catalog API course gives 250 as the limit for values that feed filter search,⁠^{[3]BigCommerce Developer Learning. Images, Videos, and Custom Fields} so 250 is the safe number.

The value accepts HTML, CSS and JavaScript, to format text or embed images and video; the name does not. BigCommerce warns of one consequence: anyone who can edit custom fields can add scripts to the value, even without the permission to manage scripts.⁠^{[1]BigCommerce, help center. Custom Fields}

Three uses beyond the product page, each with its condition:⁠^{[1]BigCommerce, help center. Custom Fields}

• Filters. On Scale plans or higher with product filtering turned on, each custom field can serve as a filter on category, brand and search results pages. The filter is created automatically, but it does not appear until you mark it visible. If the name matches a product option's name, it does not show as a filter; if it matches a default filter, such as brand, price or category, BigCommerce throws the error "Failed to save filters. Duplicate usage of facet."
• Channels. Google and Meta ask for data that does not always have a field of its own in BigCommerce, and depending on the connector you use you can supply it as custom fields. With Feedonomics, some of them, such as age and gender, are mapped automatically.
• Languages. In stores with several storefronts, the GraphQL Admin API lets you translate a custom field for each channel's language. It is only available to Enterprise stores and partner sandboxes.⁠^{[4]BigCommerce Dev Center. Product custom fields (International Enhancements for Multi-Storefront)}

BigCommerce itself uses this slot in its catalog enrichment tool, Catalog Enrichment: of the seven fields it generates, four overwrite default data (name, description, meta description and SEO title) and three are added as custom fields, intended for answer engines, and its documentation says whether they are displayed depends on the theme.⁠^{[5]BigCommerce Dev Center. Fields in an enrichment}

In a store

Fictional example. Harbor Linen, an invented BigCommerce store, adds the fabric to its linen shirt (product 112) through the API:

{
  "name": "Fabric",
  "value": "washed linen"
}

What happens next depends on the theme. In Cornerstone, BigCommerce's default theme, the template that renders custom fields in version 6.22.0 is this:⁠^{[6]BigCommerce on GitHub. Cornerstone, the default Stencil theme (release 6.22.0)}

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

It loops over the product's list and writes each pair as a term and its definition. The three curly braces in {{{value}}} let the value through unescaped, which is what allows the HTML the help center talks about. Cornerstone calls that template from the product page, in the details list, unless the theme setting show_custom_fields_tabs is on: then it renders them in a tab alongside the description.⁠^{[6]BigCommerce on GitHub. Cornerstone, the default Stencil theme (release 6.22.0)} In the HTML of product page 112, <dt class="productView-info-name">Fabric:</dt> would appear, followed by its value.

And an absence worth knowing about: Cornerstone 6.22.0's Product JSON-LD block includes no custom field at all. It carries the name, the SKU, the MPN, the GTIN, the brand, the description, the image, the offer and, if the store shows them, the ratings, but not the fabric.⁠^{[6]BigCommerce on GitHub. Cornerstone, the default Stencil theme (release 6.22.0)} The data is on the page for whoever reads it, and it is not in its structured data.

How to check it

1. Open the product in the control panel and look at the custom fields section: how many there are and what they are called. If they are getting close to 200, or a value goes over 250 characters, you need to split them up.⁠^{[2]BigCommerce API Reference. Create Product Custom Field}
2. Open the published product page and its source code (Ctrl+U in Chrome) and search for the exact value of one of them. If it does not appear, the theme is not rendering it.
3. Search for application/ld+json in the same source and check whether the data is in the markup. In Cornerstone, out of the box, it will not be.⁠^{[6]BigCommerce on GitHub. Cornerstone, the default Stencil theme (release 6.22.0)}
4. Review the names before using them as filters: none should match a product option or the default brand, price or category filters.⁠^{[1]BigCommerce, help center. Custom Fields}
5. Read the values that carry code. Anyone with permission to edit them may have added a script.⁠^{[1]BigCommerce, help center. Custom Fields}

Related concept: metafields

BigCommerce also has metafields, and the difference is audience. A metafield is a key-and-value pair defined by a developer, which can be attached to products, variants, categories, brands, orders, customers and other objects, and each one carries a permission: private to the app that created it, readable or editable by other apps, or also accessible from the storefront. They are managed through the API and, to show them in the store, read with the GraphQL Storefront API.⁠^{[8]BigCommerce Dev Center. Metafields} A custom field, by contrast, is born to be seen on the product page.⁠^{[2]BigCommerce API Reference. Create Product Custom Field} What the customer should read goes in a custom field; what an app needs to store goes in a metafield. The entry on metafields explains how they work on Shopify.

To go further, the entry on Stencil explains the theme engine that decides what gets rendered, and the publishing by platform reading path orders the rest of the terms.