Managing Multi-Storefronts in BigCommerce

Multi-Storefront in BigCommerce enables centralized management of multiple storefronts using a single backend. Each storefront operates under a unique channel_id and site_id for theme isolation, product visibility, pricing, and checkout configurations.

APIs such as the Channels API, the Product Channel Assignment API, and the Themes API support storefront creation, catalog scoping, and layout customization. GraphQL and REST APIs use channelId to filter data per storefront, enabling region-specific user experiences and content delivery, including localized video playback.

What is Multi-Storefront in BigCommerce?

Multi-Storefront allows you to operate multiple unique storefronts via a single BigCommerce store. Each storefront is defined by a unique channel_id and site_id, which isolate storefront data such as catalog products and visibility, pricing and promotions, theme and layout configurations, and payment gateways and tax rules. This architecture supports running region-specific stores, brand variations, or niche channels under one BigCommerce account.

Components and APIs for Multi-Storefront Management

Storefront Isolation with Channel IDs

Every storefront channel in BigCommerce is uniquely identified by a channel_id and site_id, which ensures data isolation.

Example: Fetching Storefront Details

code

curl -X GET "https://api.bigcommerce.com/stores/{store_hash}/v3/channels/23" \

code

-H "X-Auth-Token: {token}" \

code

-H "Accept: application/json"

Explanation:

Starts with curl -X GET to send an HTTP GET request to the specified BigCommerce API endpoint.
Targets "https://api.bigcommerce.com/stores/{store_hash}/v3/channels/23" to fetch details for channel ID 23 in the given store.
Adds the header X-Auth-Token: {token} to authenticate the request using an API token.

Managing Product Catalog and Pricing Per Storefront

The Catalog API and Product Channel Assignment API allow selective product visibility and pricing per storefront. Each channel can override default prices or hide products based on business rules.

Example: Assigning Products to Storefronts

code

curl -X POST "https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/567/channels" \

code

-H "X-Auth-Token: {token}" \

code

-H "Content-Type: application/json" \

code

-d '{

code

"channel_ids": [23]

code

}'

Explanation:

Adds the header X-Auth-Token: {token} to authenticate the API request with a valid access token.
Includes the header Content-Type: application/json to specify that the request body is formatted as JSON.
Sends a JSON payload with "channel_ids": [23] to assign the product to channel ID 23.

Example: Setting Custom Prices for Storefronts

code

curl -X POST "https://api.bigcommerce.com/stores/{store_hash}/v3/pricelists" \

code

-H "X-Auth-Token: {token}" \

code

-H "Content-Type: application/json" \

code

-d '{

code

"name": "EU Premium Pricing",

code

"active": true,

code

"channel_id": 23,

code

"prices": [

code

"product_id": 567,

code

"price": 89.99

code

}'

Explanation:

Adds the header X-Auth-Token: {token} to authorize the request using a valid API token.
Includes the header Content-Type: application/json to indicate that the request body is in JSON format.
Sends a JSON payload defining a new price list named "EU Premium Pricing", marked as active and linked to channel ID 23.
Includes a prices array that sets the price of product ID 567 to 89.99 for this specific price list.

Theme and Layout Customization Per Storefront

Themes are scoped per storefront using the Themes API or Admin UI. The active channel_id determines which layout assets the Storefront API resolves for requests.

Example: Assigning a Theme to a Channel

code

curl -X POST "https://api.bigcommerce.com/stores/{store_hash}/v3/channels/23/themes" \

code

-H "X-Auth-Token: {token}" \

code

-H "Content-Type: application/json" \

code

-d '{

code

"uuid": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv"

code

}'

Explanation:

Adds the header X-Auth-Token: {token} to authenticate the request using a valid API token.
Includes the header Content-Type: application/json to specify that the request body is formatted as JSON.
Sends a JSON payload with a "uuid" that identifies the theme being applied to the channel.

Example: Conditional Theme Logic in Stencil Templates

code

<script>

code

// Inject channel-specific CSS

code

{% if channel_id == 23 %}

code

<link rel="stylesheet" href="{{cdn 'assets/css/premium.css'}}">

code

{% else %}

code

<link rel="stylesheet" href="{{cdn 'assets/css/standard.css'}}">

code

{% endif %}

code

</script>

Explanation:

Checks if channel_id is equal to 23 using a conditional {% if %} statement.
Loads premium.css from the CDN when the current channel is 23 to apply premium styling.
Loads standard.css from the CDN for all other channels as a fallback style.
End the conditional block with {% endif %} to complete the logic.

Example: Fetching the Active Theme for a Channel

code

curl -X GET "https://api.bigcommerce.com/stores/{store_hash}/v3/channels/23/active-theme" \

code

-H "X-Auth-Token: {token}"

Configuring Checkout, Payment, and Taxes by Storefront

Storefronts enforce independent payment gateways and tax rules via channel_id-scoped API configurations. The Checkout API applies channel-specific logic (e.g., enabling SCA for EU channels via payment_instruments restrictions) while tax overrides use the Tax API with location_id bindings.

Example: Enabling Stripe and Enforcing SCA (Strong Customer Authentication)

code

curl -X PUT "https://api.bigcommerce.com/stores/{store_hash}/v3/channels/23/payment-providers/stripe" \

code

-H "X-Auth-Token: {token}" \

code

-d '{"is_enabled": true, "sca_enforced": true}'

Explanation:

Adds the header X-Auth-Token: {token} to authenticate the request using a valid API token.
Sends a JSON payload with "is_enabled": true to activate Stripe as a payment provider for the specified channel.
Sets "sca_enforced": true to enforce Strong Customer Authentication (SCA) compliance for transactions processed through Stripe.

Example: Applying Tax Overrides

code

curl -X POST "https://api.bigcommerce.com/stores/{store_hash}/v3/tax/overrides" \

code

-H "X-Auth-Token: {token}" \

code

-d '{"channel_id": 42, "tax_zone_id": 5, "rate": 0.08}'

Explanation:

Adds the header X-Auth-Token: {token} to authorize the request using an API token.
Sends a JSON payload with "channel_id": 42 to apply the tax override to channel ID 42.
Sets "tax_zone_id": 5 to identify the geographical tax zone the override applies to.
Defines "rate": 0.08 to apply an 8% tax rate for that zone and channel.

Managing Multi-Storefronts via BigCommerce Dashboard

Creating a New Storefront Channel

Step 1: Go to Channel Manager > Create Channel.

Step 2: Assign a name, region, and base URL..

Step 3: Configure domain settings and assign a site_id.

Step 4: Set default currency, language, and tax zone.

Assigning Products to Storefronts

Step 1: Navigate to Products > View Products.

Step 2: Select the product you want to assign.

Step 3: Under Storefronts, select one or more storefronts.

Step 4: Save changes to update the catalog visibility.

Assigning and Customizing Themes

Step 1: Go to Storefront > Themes.

Step 2: Use the dropdown to switch between storefronts.

Step 3: Apply or customize a theme per storefront.

Step 4: Use theme variations to offer unique branding for each channel.

Pricing, Taxes, and Payment Setup

Pricing: Use Price Lists to define region-specific prices. Assign them via Customers > Price Lists.

Taxes: Go to Tax Settings, and create rules or overrides scoped by channel or location.

Payments: Configure different gateways for each storefront. For example, enable Stripe for one and PayPal for another.

Video Hosting Integration for Multi-Storefronts

Storing Video URLs Using Custom Fields

To associate videos with individual products, you can use custom fields to store URLs pointing to hosted video assets. This allows you to manage storefront-specific media directly through the BigCommerce API.

Example: Attach Video URLs as Custom Product Fields

code

curl -X POST "https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/456/custom-fields" \

code

-H "X-Auth-Token: {token}" \

code

-d '{

code

"name": "hero_video",

code

"value": "https://cdn.example.com/eu-product-trailer.mp4"

code

}'

Explanation:

name: The custom field key used to store video metadata.
value: The URL of the product video to display on the storefront.

Querying Video URLs via GraphQL Scoped by Channel

Once stored, these custom field values can be queried using GraphQL, scoped to a specific channelId. This ensures that only the appropriate video URL is exposed to each storefront"s frontend.

Example: Query the hero_video Field for a Product Scoped by ChannelId

code

query GetProductVideos($channelId: Int!) {

code

site(channelId: $channelId) {

code

product(entityId: 456) {

code

customFields(names: ["hero_video"]) {

code

edges { node { value } }

code

Explanation:

$channelId: The variable defining which storefront (channel) to query.
site(channelId: $channelId): Scopes the product query to a specific storefront.
product(entityId: 456): Fetches the product with ID 456.
customFields(names: ["hero_video"]): Requests the custom field storing the video URL.
node { value }: Retrieves the actual value of the custom field (video URL).

Frontend Channel-Specific Video Playback Logic

Front-end logic can dynamically adjust video behavior (such as subtitles or GDPR compliance) based on the user"s region or the current channel. This ensures regulatory alignment and a localized experience.

Example: Load GDPR Settings and EU Subtitles for EU Region Storefront

code

const channelId = userRegion.startsWith("EU") ? 23 : 42;

code

if (channelId === 23) {

code

videoPlayer.setAttribute("data-gdpr", "true");

code

videoPlayer.loadSubtitles("eu-subtitles.vtt");

code

Explanation:

channelId: Assigns 23 for EU users, otherwise assigns 42.
channelId === 23: Checks if the current channel is EU-specific.
videoPlayer.setAttribute("data-gdpr", "true"): Enables GDPR compliance for EU storefront.
videoPlayer.loadSubtitles("eu-subtitles.vtt"): Loads EU-specific subtitle file for the video.

Optimizing Video Delivery with CDNs and Signed URLs

To improve performance and control access, serve video content via CDN platforms like Cloudflare Stream or AWS CloudFront. You can use signed URLs and include channel_id to segment content delivery per storefront.

Example: Request Video via CDN with Signed Token and Channel Context

code

curl "https://cdn.example.com/video.mp4?token=${SIGNED_TOKEN}&channel_id=23"

Explanation:

Include channel_id in the query for targeted delivery.
Use signed URLs and cache control headers per channel for privacy and performance.

Managing Multi-Storefronts in BigCommerce

What is Multi-Storefront in BigCommerce?

Components and APIs for Multi-Storefront Management

Storefront Isolation with Channel IDs

Managing Product Catalog and Pricing Per Storefront

Theme and Layout Customization Per Storefront

Configuring Checkout, Payment, and Taxes by Storefront

Managing Multi-Storefronts via BigCommerce Dashboard

Creating a New Storefront Channel

Assigning Products to Storefronts

Assigning and Customizing Themes

Pricing, Taxes, and Payment Setup

Video Hosting Integration for Multi-Storefronts

Storing Video URLs Using Custom Fields

Querying Video URLs via GraphQL Scoped by Channel

Frontend Channel-Specific Video Playback Logic

Optimizing Video Delivery with CDNs and Signed URLs

Was this article helpful?