Extending existing apps

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 NameParameterEnables
Channels Settings Modifystore_channel_settingsCreating channels that reference external platforms
Channels Listings Modifystore_channel_listingsCreating 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

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.


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:

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
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.
  • 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.


typestrAllowed Values: pos, marketplace, storefront, marketing
platformstrAllowed Values: see below or in API Reference
namestrThe name the merchant will see
external_idstrAssociated ID within a system / platform outside of BC.
statusstrAllowed Values: active, inactive, connected, disconnected, archived
appobjApp configuration
idintID of the app
sectionsarray[obj]User interface section options
   ↳ titlestrLabel displayed to merchants in navigation bar
   ↳ query_pathstrPassed 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.


Channels ToolkitChannels 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 PartnersPartners 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.

Related resources



Did you find what you were looking for?