Channels
Create and manage sales channels, their sites, and their product listings.
Channels
A channel is anywhere a merchant sells their products. This encompasses headless storefronts, marketplaces, POS systems, and marketing platforms.
Platform
A channelʼs type
and platform
combination must be a valid pair as indicated in the table below.
Platform | Accepted Type |
---|---|
clover | pos |
square | pos |
stripe | pos |
talech | pos |
vend | pos |
amazon | marketplace |
belk | marketplace |
catch | marketplace |
ebay | marketplace |
etsy | marketplace |
facebook | marketplace , marketing |
hudsons_bay | marketplace |
google | marketplace , marketing |
google_shopping (deprecated) | marketing |
instagram | marketplace , marketing |
macys | marketplace |
mirakl | marketplace |
overstock | marketplace |
pinterest | marketplace |
target_plus | marketplace |
tiktok | marketplace |
wayfair | marketplace |
wish | marketplace |
walmart | marketplace |
acquia | storefront |
bigcommerce (Stencil and Blueprint) | storefront |
bloomreach | storefront |
catalyst (BigCommerce Next.js) | storefront |
deity | storefront |
drupal | storefront |
gatsby | storefront |
next (Next.js Commerce and other Next.js) | storefront |
vue | storefront |
wordpress | storefront |
custom | storefront , pos , marketing , marketplace |
Status
Allowed values for a channelʼs status
vary by channel type
.
Type | Writable Statuses |
---|---|
storefront | prelaunch , active , inactive , archived , deleted |
marketing , marketplace , pos | connected , disconnected , archived , deleted |
Warning
- You can restore a Channel with
deleted
status within 90 days after deletion by contacting the BigCommerce support team. After the 90-days grace period is over, the Channelstatus
will becometerminated
.- The
terminated
status is read-only. Channels with astatus
ofterminated
cannot be restored.
Channel listings
Channel listings allow you to manage catalog differences among different storefronts or marketplaces.
Channel site
A Channel site refers to the domain associated with a channel.
Resources
Get All Channels
GET https://api.bigcommerce.com/stores/{store_hash}/v3/channelsRequest
Returns a list of Channels.
Will always return the default BigCommerce storefront with an ID of 1
. This storefront is created by default when you provision a BigCommerce store.
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- include in query - stringChannels subresources that can be included in the response.
Allowed: currencies
- available in query - booleanFilter items based on whether the channel is currently available for integration. Setting this query parameter to
true
will return channels with the status ofprelaunch
,active
,inactive
, andconnected
. Setting this query parameter tofalse
will return channels with the status ofdisconnected
,archived
,deleted
, andterminated
. - status:in in query - arrayFilter items by a comma-separated list of statuses.Type: array[string]
Allowed: prelaunch | active | inactive | connected | disconnected | archived | deleted | terminated
- type:in in query - arrayFilter items by a comma-separated list of types.Type: array[string]
Allowed: marketplace | marketing | pos | storefront
- platform:in in query - arrayFilter items by a comma-separated list of platforms. For a list of supported platforms, see Platform.Type: array[string]Example: ["facebook by meta,amazon"]
- date_created in query - stringFilter items by date created. For example,
date_created=2024-05-14T09:34:00
ordate_created=2024-05-14
. - date_created:min in query - stringFilter items by minimum date created. For example,
date_created=2024-05-14T09:34:00
ordate_created=2024-05-14
. Returns metafields created after this date. - date_created:max in query - stringFilter items by maximum date created. For example,
date_created=2024-05-14T09:34:00
ordate_created=2024-05-14
. Returns metafields created before this date. - date_modified in query - stringFilter items by date modified. For example,
date_created=2024-05-14T09:34:00
ordate_created=2024-05-14
. - date_modified:min in query - stringFilter items by minimum date modified. For example,
date_created=2024-05-14T09:34:00
ordate_created=2024-05-14
. Returns metafields modified after this date. - date_modified:max in query - stringFilter items by maximum date modified. For example,
date_created=2024-05-14T09:34:00
ordate_created=2024-05-14
. Returns metafields modified before this date. - limit in query - integerControls the number of items per page for paginated responses.
- page in query - integerSpecifies the page number for a paginated response.
example
Response
Body
dataarray[object]
required
response
Create a Channel
POST https://api.bigcommerce.com/stores/{store_hash}/v3/channelsRequest
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- Content-Type in header with default of application/json - stringrequiredThe MIME type of the request body.
Body
external_idstring
Associated ID within a system / platform outside of BC.is_listable_from_uiboolean
Indicates if a channel can create listings from the BigCommerce UI. Default value for this field is based on the channel type and platform combination if not specified on create.is_visibleboolean
Indicates if a channel is visible within the BigCommerce merchant admin UI (control panel). Iffalse
, the channel will not show in Channel Manager nor in any channels dropdown throughout the UI. Default value for this field istrue
if not specified on create.statusstring
The status of the channel; channeltype
,platform
, andstatus
must be a valid combination.terminated
is not valid forPUT
orPOST
requests.deleted
is not valid forPOST
requests.prelaunch
is not valid forPUT
requests.Allowed: active | prelaunch | inactive | connected | disconnected | archived | deleted | terminated
namestring
requiredName of the channel as it will appear in the store control panel. The only characters it can include are Latin alphabet letters, Arabic numerals, dashes, and underscores.typestring
requiredThe type of channel; channelplatform
andtype
must be a valid combination.Allowed: pos | marketplace | storefront | marketing
platformstring
requiredThe name of the platform for the channel; channelplatform
andtype
must be a valid combination.
Create eBay Channel
Response
Body
dataobject
response
Get a Channel
GET https://api.bigcommerce.com/stores/{store_hash}/v3/channels/{channel_id}Request
1
returns the default BigCommerce storefront.Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- channel_id in path - integerrequiredThe ID of a channel.
- include in query - stringChannels subresources that can be included in the response.
Allowed: currencies
example
Response
Body
dataobject
response
Update a Channel
PUT https://api.bigcommerce.com/stores/{store_hash}/v3/channels/{channel_id}Request
Updates a Channel.
Updatable Fields
The following fields can be updated.
name
external_id
status
is_listable_from_ui
is_visible
config_meta
Note
- Partial updates are supported. In most cases, if a field that cannot be updated is passed in, the API will not respond with an error. It returns a 200 response with the object, in which you will see the field(s) were not updated.
platform
andtype
cannot be updated after a channel is created.- A channel with status
deleted
orterminated
cannot be updated.
Authentication
- X-Auth-Token in header
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequiredThe MIME type of the response body.
- channel_id in path - integerrequiredThe ID of a channel.
- Content-Type in header with default of application/json - stringrequiredThe MIME type of the request body.
Body
external_idstring
Associated ID within a system / platform outside of BC.is_listable_from_uiboolean
Indicates if a channel can create listings from the BigCommerce UI. Default value for this field is based on the channel type and platform combination if not specified on create.is_visibleboolean
Indicates if a channel is visible within the BigCommerce merchant admin UI (control panel). Iffalse
, the channel will not show in Channel Manager nor in any channels dropdown throughout the UI. Default value for this field istrue
if not specified on create.namestring
Name of the channel as it will appear in the store control panel. The only characters it can include are Latin alphabet letters, Arabic numerals, dashes, and underscores.statusstring
The status of the channel; channeltype
,platform
, andstatus
must be a valid combination.terminated
is not valid forPUT
orPOST
requests.deleted
is not valid forPOST
requests.prelaunch
is not valid forPUT
requests.Allowed: active | prelaunch | inactive | connected | disconnected | archived | deleted | terminated
Update a Facebook by Meta Channel
Response
Body
dataobject
response
See something you can improve? Edit this file on GitHub