IntegrationsChannelsGuide

Building Storefront Channels

This article documents how to use Channels Toolkit to install a storefront channel in a store’s Channel Manager (Help Center) during a single-click app installation. This article assumes you’re an experienced app and headless storefront developer familiar with channels on BigCommerce.

Prerequisites

Creating a channel

After receiving the final response of the single-click app OAuth flow auth callback, create a channel on the merchant’s store. Creating a dedicated channel for a storefront allows merchants to assign the storefront selected product listings and configure storefront-specific settings. To create a storefront channel, set type to storefront in a request to the Create a channel endpoint.

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
}

Specifying the platform

Specify the headless storefront’s platform by assigning an accepted value for platform in the request to the Create a channel endpoint.

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

See the list of Channels Platform types in the Channels API reference. You can use any platform with storefront as an accepted type.

Configuring UI sections

Define and configure the navigation menu items displayed in the channel’s dedicated control panel menu using the Create a channel menu endpoint.

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"
    }
  ]
}

Protected UI sections

BigCommerce allows the developer to toggle the location and scope of the following BigCommerce-managed settings pages between the storewide menu and channel-specific menus:

Menu item / settings pageAPI ArgumentDescription
OverviewoverviewRenders a channel-specific overview page.
Storefront Settingsstorefront_settingsRenders channel-specific storefront settings.
LocalizationlocalizationRenders channel-specific localization settings.
CarouselcarouselRenders channel-specific carousel settings.
Script Managerscript_managerRenders channel-specific script manager settings.
CurrenciescurrenciesRenders channel-specific currency settings.
PaymentspaymentsRenders channel-specific payments settings.
CheckoutcheckoutRenders channel-specific checkout settings.
DomainsdomainsRenders channel-specific domain settings.
NotificationsnotificationsRenders channel-specific notification settings.
SocialsocialRenders channel-specific social media settings.
Web pagespagesRenders channel-specific pages settings.
Data solutionsdata_solutionsRenders channel-specific data solutions settings.

The term protected section refers to the settings on the corresponding menu pages. Settings in protected sections override the default settings configured at the storewide level. Include these protected sections in requests to the Create channel menus endpoint to display BigCommerce-provided, channel-specific settings pages and corresponding menu items. Enabled protected sections precede custom sections in a channel’s menu.

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": []
}

Protected Sections

Storefront settings

Include the storefront_settings protected section in a Channel Menu’s bigcommerce_protected_app_sections array to render the BigCommerce-provided Storefront Settings menu item in the channel’s navigation and corresponding settings page, and protect channel storefront settings from those set for the store in general.

Channel Storefront Settings

Read channel-specific storefront settings using the Settings API. For example, you can see a storefront’s category settings using the Get storefront category settings endpoint.

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

Currencies settings

Include the currencies protected section in a Channel Menu’s bigcommerce_protected_app_sections array to render the BigCommerce-provided Currencies menu item in the channel’s navigation and corresponding settings page, and protect channel currency settings from storewide currency settings.

Channel Currency Settings

You can manage channel specific currency settings using the Channels API Currency Assignments endpoints. For example, you can use the Get channel currency assignments endpoint to learn more about a channel’s currency assignments.

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

Notification settings

Include the notifications protected section in a Channel Menu’s bigcommerce_protected_app_sections array to render the BigCommerce-provided Notifications menu item in the channel’s navigation and corresponding settings page, and protect channel notifications from storewide notifications settings.

Channel Notification Settings

Articles

Endpoints