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
- Familiarity with channels on BigCommerce
- Experience building apps
- Experience building headless storefronts
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.
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.
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.
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.
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.
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.
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
.
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.
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
.
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.