Management APIs
Building Apps
Quick Start
Guide
Tutorials
Building Storefronts
Overview
Embedded Checkout
Next.js Commerce
Managing Currencies
Guide
Partner Information
Becoming A Partner
Getting Started
POS Solutions
ERP Solutions
PIM Solutions
OMS Solutions
Marketing Solutions
Shipping Solutions
Payment Solutions

Building Storefront Channels

This article documents how to use Channels Toolkit to install a storefront channel into Channel Manager 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.

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,
      "sections": [
        {
          "title": "Overview",
          "query_path": "overview"
        },
        {
          "title": "Storefront Settings",
          "query_path": "storefront_settings"
        },
        {
          "title": "Domains",
          "query_path": "domains"
        },
        {
          "title": "Notifications",
          "query_path": "notifications"
        },
        {
          "title": "Currencies",
          "query_path": "currencies"
        }
      ]
    }
  }
}

Open in Request Runner

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",
  ...
  }
}

Open in Request Runner

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 channel’s UI tabs displayed in the control panel by passing in a config_meta object.

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/channels
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

{
  "name": "Deity Falcon PWA Storefront",
  ...
  "config_meta": {
    "app": {
      "id": 112233,
      "sections": [
        {
          "title": "Overview",
          "query_path": "overview"
        }
          ...
      ]
    }
  }
}

Note

You can find an app’s ID in the URL when editing the app in the Developer Portal.

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 request to display BigCommerce provided channel specific settings.

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",
  ...
  "config_meta": {
    "app": {
      "id": 112233,
      "sections": [
        {
          "title": "Storefront Settings",
          "query_path": "storefront_settings"
        },
        {
          "title": "Domains",
          "query_path": "domains"
        },
        {
          "title": "Notifications",
          "query_path": "notifications"
        },
        {
          "title": "Currencies",
          "query_path": "currencies"
        }
      ]
    }
  }
}

Note

  • Any content an app attempts to render to the control panel iFrame for a protected section will be overridden by the BigCommerce provided content.

Storefront settings

Include the Storefront Settings protected section in the channel’s config_meta object to render the BigCommerce provided Storefront Settings tab on the channel’s 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.

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

Open in Request Runner

Response:

{
  "data": {
    "listing_mode": null,
    "default_product_sort": "bestselling",
    "category_tree_depth": 0
  },
  "meta": {}
}

View the settings API Reference.

Currencies settings

Include the Currencies protected section in the channel’s config_meta object to render the BigCommerce provided Currencies tab on the channel’s 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.

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}}/v3/channels/{channel_id}/currency-assignments
X-Auth-Token: {{ACCESS_TOKEN}}
X-Auth-Client: {{CLIENT_ID}}
Content-Type: application/json
Accept: application/json

Open in Request Runner

Response:

{
  "data": {
    "channel_id": 1,
    "default_currency": "USD",
    "enabled_currencies": [
      "USD",
      "CAD"
    ]
  },
  "meta": {}
}

View the Channels API reference.

Notification settings

Include the Notifications protected section in the channel’s config_meta object to render the BigCommerce provided Notifications tab on the channel’s settings page.

Channel Notification Settings

Resources