Thanks for being patient while we implement your feedback to improve the developer experience.
API Docs
Building Channels
Tutorials
Build a Storefront Channel

Building Storefront Channels

This article documents how to use Channels Toolkit to install a storefront channel into Channel Manager (opens in a new tab) during a single-click app's installation. We'll assume you're an experienced app and headless storefront developer familiar with channels on BigCommerce.

Prerequisites

Creating a channel

After receiving the POST response at the end of the single-click app OAuth flow, create a channel on the merchant's store. This allows merchants to assign product listings to the storefront and configure storefront specific settings. To create a storefront channel, set type to storefront in the create a channel request.

Example request: Create a channel
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/channels
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "name": "Custom PWA Storefront",
  "type": "storefront",
  "platform": "custom",
  "external_id": "",
  "status": "connected",
  "is_listable_from_ui": true,
  "is_visible": true,
  "config_meta": {
    "app": {
      "id": 112233
    }
  }
}

View reference documentation for this request.

Specifying the platform

Specify the headless storefront's platform by assigning an accepted value for platform in the create channel request.

Example request: Create a channel
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/channels
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "name": "Deity PWA Storefront",
  "type": "storefront",
  "platform": "deity",
  ...
  }

Accepted values

PlatformAccepted Type
wordpressstorefront
drupalstorefront
acquiastorefront
bloomreachstorefront
deitystorefront
customstorefront, pos, marketing, marketplace

Configuring UI sections

Define and configure the navigation menu items displayed in the control panel for the channel by creating channel menus using the Channel Menus API.

Example request: Create channel menus
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/channels/{{CHANNEL_ID}}/channel-menus
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
   "bigcommerce_protected_app_sections":[],
   "custom_app_sections":[
      {
         "title":"Overview",
         "query_path":"overview"
      }
   ]
}

These UI sections were previously managed via config_meta. As of March 29, 2022, changes to UI sections via config_meta are dual written to the new API when config_meta.app.sections exists in the payload.

Protected UI sections

The following protected sections are provided by BigCommerce:

TitleQueryDescription
Storefront Settingsstorefront_settingsRenders channel specific storefront settings
DomainsdomainsRenders channel specific domain settings
NotificationsnotificationsRenders channel specific notification settings
CurrenciescurrenciesRenders channel specific currency settings

Include protected sections in the create channel menus request to display BigCommerce-provided channel-specific settings pages.

Example request: Create channel menus
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/channels/{{CHANNEL_ID}}/channel-menus
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
   "bigcommerce_protected_app_sections":[
      "storefront_settings",
      "currencies",
      "domains"
   ],
   "custom_app_sections":[]
}

Included protected sections display above custom sections.

Protected Sections

Storefront settings

Include the storefront_settings protected section in the Channel Menus' bigcommerce_protected_app_sections array to render the BigCommerce-provided Storefront Settings menu item in the channel's navigation and corresponding settings page.

Channel Storefront Settings

Read channel specific storefront settings using the Settings API. For example, to get storefront category settings, send a GET request to /v3/settings/storefront/category.

Example request: Get storefront category settings
GET /stores/{{STORE_HASH}}/v3/settings/storefront/category?channel_id={{CHANNEL_ID}}
Host: api.bigcommerce.com
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

View the settings API Reference.

Currencies settings

Include the currencies protected section in the Channel Menus' bigcommerce_protected_app_sections array to render the BigCommerce-provided Currencies menu item in the channel's navigation and corresponding settings page.

Channel Currency Settings

You can manage channel specific currency settings using the Channel API Currency Assignments endpoints. For example, To get a channel's currency assignments, send a GET request to /v3/channels/{{CHANNEL_ID}}/currency-assignments.

Example request: Get channel currency assignments
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}}/v3/channels/{{CHANNEL_ID}}/currency-assignments
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

View the Channels API reference.

Notification settings

Include the notifications protected section in the Channel Menus' bigcommerce_protected_app_sections array to render the BigCommerce-provided Notifications menu item in the channel's navigation and corresponding settings page.

Channel Notification Settings

Related resources

Articles

Endpoints