Branding & Theming

Branding your storefront comes in three tiers, in increasing order of effort. Your logo is a BigCommerce setting you already control. Your colors and typographic scale are a store setting you can change yourself. Custom fonts, icons and bespoke themes are a rebuild we do for you.

Tier 1: Change it in BigCommerce

Asset	Where
Store logo	BigCommerce admin → Storefront → Logo
Store name	BigCommerce admin → Settings → Store profile
Social links	BigCommerce admin → Settings → Social media

Your storefront reads all three from BigCommerce, so changing them there changes your storefront. The logo appears in the header and footer, and the social links become the footer's social icons.

Tier 2: Change your palette yourself

Appearance is controlled by two settings in the evolve_theme namespace. See Store Settings for how to set a metafield.

Setting	Default	What it does
`themeName`	`EvolveMain`	Which shipped theme to use
`themeSettings`	`{}`	A JSON object merged over that theme, overriding any part of it

Choose a theme

Two themes are intended for customer use:

`themeName`	Description
`EvolveMain`	The default. Deep purple and pale blue, with light and dark modes.
`EvolveBlue`	A blue variant of `EvolveMain`, inheriting the same layout and components.

Switch theme - 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_theme",
      "key": "themeName",
      "value": "EvolveBlue",
      "permission_set": "read_and_sf_access"
    }'

Override colors

themeSettings is deep-merged over the theme, so you only specify what you're changing. Everything else keeps the theme's value.

The most common change is the primary and secondary colors:

themeSettings - brand colors
{
    "palette": {
        "primary": { "main": "#13005a", "contrastText": "#ffffff" },
        "secondary": { "main": "#cef1ff", "contrastText": "#13005a" }
    }
}

Stringified for the metafield value, that becomes:

Set brand colors - 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_theme",
      "key": "themeSettings",
      "value": "{\"palette\":{\"primary\":{\"main\":\"#13005a\",\"contrastText\":\"#ffffff\"},\"secondary\":{\"main\":\"#cef1ff\",\"contrastText\":\"#13005a\"}}}",
      "permission_set": "read_and_sf_access"
    }'

Escaping matters

The value must be valid JSON, stringified, with escaped double quotes. Single quotes are accepted by BigCommerce but silently ignored by your storefront, so the site simply looks unchanged. See JSON values.

What you can override

Group	Examples of what you can set
`palette.primary`, `palette.secondary`	`main`, `light`, `dark`, `contrastText`
`palette.text`	`primary`, `secondary`, `main`, `highlight`, `alert`
`palette.background`	`default`, `paper`, `main`, `topBar`, `contentBar`, `carousel`
`palette.icon`, `palette.badge`, `palette.base`, `palette.border`	`main`, `contrastText`, `highlight`
`typography`	Font sizes and weights per text style
`spacing`, `shape`	Base spacing unit, corner radius

Use hex values. contrastText is the color drawn on top of that color, so set both together. Changing main without contrastText is the usual cause of unreadable buttons.

Check both modes

EvolveMain and EvolveBlue both have a dark mode, and the shopper-facing toggle is on by default. After a palette change, view your storefront in both modes. If you'd rather not support dark mode, set themeDarkModeToggle to false. See Settings Reference.

Tier 3: Send it to us

These need a rebuild of your storefront, so send them to us and we'll apply them.

Asset	Format	Specification
Favicon	`.ico`
App icon	PNG	180 × 180 pixels
Typography	`.woff2`	The licensed font files, plus confirmation of the web license

Fonts

Adding a font family is a code change rather than a setting, because the font files have to be built into your storefront. You must supply the .woff2 files and they must be licensed for web use. We can't download fonts on your behalf.

Also in this tier: a bespoke theme, changes to layout or component structure, and anything that isn't a color, size or spacing value. See Advanced Customizations.

How to submit assets

Send your assets to support with your tenant subdomain. We apply them, rebuild your storefront and confirm when it's live. Branding changes go live for all shoppers at once; there is no staged rollout.

Two things branding doesn't cover

BigCommerce checkout. Your shoppers check out on BigCommerce, and that page is styled in the BigCommerce admin, not here. Style it there so the handover doesn't look abrupt.

Social share images. There's no separate share-image slot. When a product or category link is shared, the preview image is that product's or category's own image. See SEO.

Tier 1: Change it in BigCommerce​

Tier 2: Change your palette yourself​

Choose a theme​

Override colors​

What you can override​

Tier 3: Send it to us​

How to submit assets​

Two things branding doesn't cover​

See also​