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

Platform	Accepted Type
`wordpress`	`storefront`
`drupal`	`storefront`
`acquia`	`storefront`
`bloomreach`	`storefront`
`deity`	`storefront`
`custom`	`storefront`, `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:

Title	Query	Description
`Storefront Settings`	`storefront_settings`	Renders channel specific storefront settings
`Domains`	`domains`	Renders channel specific domain settings
`Notifications`	`notifications`	Renders channel specific notification settings
`Currencies`	`currencies`	Renders 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.