Extending Sales Channel Apps with Channels Toolkit

This article provides a guide to partners who would like to update or replace their existing sales channel apps to leverage new functionality available via Channels Toolkit.

Step 1: Update API credentials

Existing sales channel apps need app credentials with updated OAuth scopes to authenticate and authorize requests to Channels Toolkit APIs. Login to the Developer Portal (opens in a new tab) to update your app's credentials. Channel APIs require the following scopes:

UI Name	Parameter	Enables
Channels Settings Modify	`store_channel_settings`	Creating channels that reference external platforms
Channels Listings Modify	`store_channel_listings`	Creating and reading product listing information

See our Guide to API Accounts for more information on app credentials.

Step 2: Integrate channel API

To be visible in Channel Manager once installed, apps must meet certain requirements. All channel apps are required to use BigCommerce’s Channel API. Select partner apps have additional Channel API implementation requirements to facilitate being marketed in Channel Manager.

All partners

Create a Channel (for each platform the app enables a merchant to sell on) - this enables the channel to be displayed within the “Manage” screen in the new Channel Manager for merchants, once the app has been installed.
Create a Channel request must include app_id at a minimum in the app config object.

Channel manager example

Extending Existing Apps 01

Select partners

Update UI to use BigDesign (opens in a new tab) and the general design patterns and user flows demonstrated in the sample app (shown in the screenshots below) with channel name, icon, and menu nav sections.
Include sections in the Channel API request in the app config object.

Channel app import section

Extending Existing Apps 03

Channel app settings section

Extending Existing Apps 04

Step 3: Migrate existing data

Channels - Register a channel for all existing merchants using the app.
Orders - Add channel_id with the corresponding channel ID for the merchant and which channel the order was placed on, if orders are synced to BigCommerce.
Listings (optional) - Create channel specific product listings. This is primarily necessary for storefronts, marketplaces, and marketing type of channels.

App requirements

Although the sample app shown in the screenshots above is for a point of sale integration, we've designed Channels Toolkit to be flexible enough to build any type of sales channel app, and each type of channel app has its own specific requirements centered around ensuring performance and user experience best practices.

The above "updating existing app" data applies; however, non-POS channel apps are not necessarily required to use the same sections and user flows shown in the example app screenshots.

Storefronts

All Partners:

Add usage of Sites and Routes API so that links generated within BigCommerce, such as "view storefront" and links sent in transactional emails to shoppers, will use the headless storefront's correct URL.

Marketplaces and marketing

All Partners:

Must use Listings API if supporting per product listings.

Sample configuration

To create or modify a channel app's configuration, send a POST or PUT request to /stores/{{STORE_HASH}}/v3/channels:

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
 
[{
    "type": "type of channel",
    "platform": "sales channel platform",
    "name": "name of the sales channel",  // Name displayed to merchant
    "external_id": "",
    "status": "connected",
    "config_meta": {
      "app": {
        "id": 123,                        // ID of the app
        "sections": [{                    // Label displayed to merchant in BigCommerce navigation bar
          "title": "Overview",            // query param passed app iframe
          "query_path": "overview"
         }, {
         "title": "Settings",
         "query_path": "settings"
        }]
      }
    }
}]

You can find the app ID in the URL when editing the app in the Developer Portal (opens in a new tab). For more information, see Finding an App's ID.
config_meta.app.id is optional; however, if you're building an app that creates or manages a channel, we recommend including the app ID to ensure the user interface in the BigCommerce control panel works properly.
Select partners who are promoted in the Channel Manager must build an app, and include the app ID in the create channel request.

Properties

Property	Type	Description
`type`	str	Allowed Values: pos, marketplace, storefront, marketing
`platform`	str	Allowed Values: see below or in API Reference
`name`	str	The name the merchant will see
`external_id`	str	Associated ID within a system / platform outside of BC.
`status`	str	Allowed Values: active, inactive, connected, disconnected, archived
`app`	obj	App configuration
↳ `id`	int	ID of the app
↳ `sections`	array[obj]	User interface section options
↳ `title`	str	Label displayed to merchants in navigation bar
↳ `query_path`	str	Passed to app's iframe. Ex: `https://<store_url>/manage/channel/2/app?id=5&section=overview`

Accepted Platforms and Types See the list of Channels Platform types in the Channels API reference.

We discourage using google_shopping as BigCommerce has deprecated this platform. Instead, we have added support for marketing and marketplace types on the google platform.

For a complete Channel API reference (including request schemas and property descriptions), see: API Reference Channels and Listings.

Terminology

Term	Definition
Channels Toolkit	Channels Toolkit is a set of tools, UI patterns, guidelines, and APIs provided by BigCommerce to enable partners and developers to extend the BigCommerce ecosystem by building sales channel integrations (whether they are point of sale, marketing, marketplace, social, or headless storefronts) that are more deeply embedded within the BigCommerce control panel.
Select Partners	Partners approved by BigCommerce to be marketed and discoverable as sales channel providers within the new Channel Manager. These are partners who offer what we know to be best in breed integrations to key sales channels that help merchants grow their business.

Select partners have slightly more stringent requirements for their sales channel apps due to the high visibility and marketability of their apps directly within the BigCommerce control panel.

For a high-level overview and more information on Channels Toolkit, see Channels Overview.