Store Settings

Your storefront reads its settings from channel metafields on your BigCommerce store. Because they're read at request time, a settings change takes effect on your storefront without a redeploy and without any involvement from us.

Prerequisites

A Management API token with the Channel settings scope set to modify, and your store hash and channel ID. See Prerequisites.

The three namespaces

Settings are grouped into three metafield namespaces:

Namespace	Controls	Reference
evolve_features	Storefront behavior: which features are on, navigation depth, Image Engine options	Settings Reference
evolve_gtm	Google Tag Manager and marketing attribution	Analytics & Tags
evolve_theme	Appearance: theme choice and palette overrides	Branding & Theming

Any setting you haven't created a metafield for falls back to its default. You only need metafields for the things you want to change.

Set a setting

Create a metafield on your channel with the setting's key as key and the value as a string:

Set a setting - Sample Request

curl -X POST 'https://api.bigcommerce.com/stores/{store_hash}/v3/channels/{channel_id}/metafields' \
    -H 'X-Auth-Token: {management_api_token}' \
    -H 'Content-Type: application/json' \
    -d '{
      "namespace": "evolve_features",
      "key": "navigationDepth",
      "value": "4",
      "permission_set": "read_and_sf_access",
      "description": "Show four levels of category menu"
    }'

permission_set is required

permission_set must be read_and_sf_access. Without it your storefront cannot read the metafield, and the setting silently has no effect.

List your settings

To see what you've already set in a namespace:

List settings - Sample Request

curl 'https://api.bigcommerce.com/stores/{store_hash}/v3/channels/{channel_id}/metafields?namespace=evolve_features' \
    -H 'X-Auth-Token: {management_api_token}'

The response includes each metafield's id, which you need in order to change or remove it.

Change a setting

Update a setting - Sample Request

curl -X PUT 'https://api.bigcommerce.com/stores/{store_hash}/v3/channels/{channel_id}/metafields/{metafield_id}' \
    -H 'X-Auth-Token: {management_api_token}' \
    -H 'Content-Type: application/json' \
    -d '{ "value": "5" }'

Remove a setting

Deleting the metafield returns the setting to its default:

Delete a setting - Sample Request

curl -X DELETE 'https://api.bigcommerce.com/stores/{store_hash}/v3/channels/{channel_id}/metafields/{metafield_id}' \
    -H 'X-Auth-Token: {management_api_token}'

Values are always strings

BigCommerce stores every metafield value as a string. Your storefront converts it to the type the setting expects:

Setting type	Write it as	Examples
Boolean	"true" / "false" (or "1" / "0")	"true"
Number	The digits, quoted	"4"
Text	The text	"registered"
JSON	Valid JSON, stringified, with escaped double quotes	"{\"palette\":{\"primary\":{\"main\":\"#13005a\"}}}"

JSON values

Two settings take a JSON object: themeSettings and marketingParameters. Two mistakes account for nearly every problem with them:

Wrong - single quotes

"value": "{ 'palette': { 'primary': { 'main': '#13005a' } } }"

BigCommerce accepts this, but your storefront can't parse it, so the setting is ignored and the default is used. There is no error message. The site simply looks unchanged.

Wrong - a raw object instead of a string

"value": { "palette": { "primary": { "main": "#13005a" } } }

BigCommerce rejects this outright with error.expected.jsstring.

Correct - stringified, with escaped quotes

"value": "{\"palette\":{\"primary\":{\"main\":\"#13005a\"}}}"

tip

If a JSON setting appears to do nothing, that's the symptom of invalid JSON. Paste the unescaped value into a JSON validator before you try anything else.

Limits and constraints

• 250 metafields per namespace, per channel, which is well beyond what you'll need.
• No admin UI. BigCommerce has no screen for channel metafields, so they're managed with the Management API, a script, or a third-party metafield app.
• Never store a secret in a metafield. Metafields created with read_and_sf_access are readable from the browser. If you have any questions about specific values, contact us for clarification.

Settings we manage for you

Some settings aren't safe or sensible to expose as metafields. Ask support to change these:

Setting	What it affects
Cache lifetime and cache headers	How long pages and catalog data are cached before refreshing
Diagnostic logging level	Temporary verbose logging while we investigate an issue
reCAPTCHA v3 keys	Spam protection on storefront forms
Image Search origin and credentials	Enabling Evolve Image Search
Image Engine origin and credentials	Enabling Evolve Image Engine
Image Optimization URL template	Routing your product images through Evolve Image Optimization
robots.txt contents	What crawlers are asked not to index

When you request a change, include your tenant subdomain, the setting, and the value you want.

Next Steps

Settings Reference — every setting, its default on BigCommerce, and what it does.