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
`square`	`pos`
`stripe`	`pos`
`vend`	`pos`
`clover`	`pos`
`talech`	`pos`
`facebook by meta`	`marketplace`,`marketing`
`instagram by meta`	`marketplace`,`marketing`
`amazon`	`marketplace`
`ebay`	`marketplace`
`pinterest`	`marketplace`
`wayfair`	`marketplace`
`overstock`	`marketplace`
`etsy`	`marketplace`
`wish`	`marketplace`
`walmart`	`marketplace`
`bigcommerce`	`storefront`
`gatsby`	`storefront`
`wordpress`	`storefront`
`drupal`	`storefront`
`acquia`	`storefront`
`bloomreach`	`storefront`
`deity`	`storefront`
`next`	`storefront`
`vue`	`storefront`
`google_shopping`	`marketing`
`custom`	`storefront`, `pos`, `marketing`, `marketplace`

Status

Allowed values for a channel's status vary by channel type and platform.

Type	Platform	Allowed Statuses
`storefront`	`bigcommerce`	`prelaunch`, `active`, `inactive`, `archived`, `deleted`
`storefront`	Is not `bigcommerce`	`prelaunch`, `active`, `inactive`, `archived`, `deleted`
`marketing`, `marketplace`, `pos`	N/A	`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 Channel status will become terminated.

The terminated status is read-only. Channels with a status of terminated 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/channels

Request

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 - required

Parameters

store_hash in path - string
include in query - string
Channels subresources that can be included in the response.
available in query - boolean
Filter items based on whether the channel is currently available for integration. Setting this query parameter to true will return channels with the status of prelaunch, active , inactive, and connected. Setting this query parameter to false will return channels with the status of disconnected, archived, deleted, and terminated.
status:in in query - array
Filter items by a comma-separated list of statuses.
type:in in query - array
Filter items by a comma-separated list of types.
platform:in in query - array
Filter items by a comma-separated list of platforms. For a list of supported platforms, see Platform.
date_created in query - string
Filter items by date_created. For example, date_created=2019-09-04T00:00:00, date_created=2019-09-04, or date_created=1567573200
date_created:min in query - string
Filter items by minimum date_created. For example, date_created:min=2019-09-04T00:00:00, date_created:min=2019-09-04, or date_created:min=1567573200
date_created:max in query - string
Filter items by maximum date_created. For example, date_created:max=2019-09-04T00:00:00, date_created:max=2019-09-04, or date_created:max=1567573200
date_modified in query - string
Filter items by date_modified. For example, date_modified=2019-09-04T00:00:00, date_modified=2019-09-04, or date_modified=1567573200
date_modified:min in query - string
Filter items by minimum date_modified. For example, date_modified:min=2019-09-04T00:00:00, date_modified:min=2019-09-04, or date_modified:min=1567573200
date_modified:max in query - string
Filter items by maximum date_modified. For example, date_modified:max=2019-09-04T00:00:00, date_modified:max=2019-09-04, or date_modified:max=1567573200
limit in query - integer
Controls the number of items per page for paginated responses.
page in query - integer
Specifies the page number for a paginated response.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/channels' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

dataarray[object]
metaobject
Data about the response, including pagination.

response

{
  "data": [
    {
      "id": 1,
      "icon_url": "https://storage.googleapis.com/bigcommerce-production-dev-center/images/bigcommerce_icon.svg",
      "is_listable_from_ui": true,
      "is_visible": true,
      "date_created": "2021-05-07T14:54:51Z",
      "external_id": "",
      "type": "storefront",
      "platform": "bigcommerce",
      "date_modified": "2021-05-07T14:54:51Z",
      "name": "Test Store",
      "status": "prelaunch"
    },
    {
      "id": 664179,
      "icon_url": "https://storage.googleapis.com/bigcommerce-production-dev-center/images/amazon_icon.svg",
      "is_listable_from_ui": true,
      "is_visible": true,
      "date_created": "2021-05-10T20:32:40Z",
      "external_id": "",
      "type": "marketplace",
      "platform": "amazon",
      "date_modified": "2021-05-13T14:25:54Z",
      "name": "Amazon",
      "status": "connected"
    },
    {
      "id": 667159,
      "icon_url": "https://storage.googleapis.com/bigcommerce-production-dev-center/images/facebook_icon.svg",
      "is_listable_from_ui": false,
      "is_visible": true,
      "date_created": "2021-05-13T15:41:39Z",
      "external_id": "",
      "config_meta": {
        "app": {
          "id": 123,
          "sections": [
            {
              "title": "Overview",
              "query_path": "overview"
            },
            {
              "title": "Settings",
              "query_path": "settings"
            }
          ]
        }
      },
      "type": "marketplace",
      "platform": "facebook by meta",
      "date_modified": "2021-05-13T15:41:39Z",
      "name": "Facebook by Meta",
      "status": "connected"
    }
  ],
  "meta": {
    "pagination": {
      "per_page": 2,
      "total": 8,
      "count": 2,
      "links": {
        "previous": "?page=1&limit=2",
        "current": "?page=2&limit=2",
        "next": "?page=3&limit=2"
      },
      "total_pages": 4,
      "current_page": 2
    }
  }
}

Create a Channel

POST https://api.bigcommerce.com/stores/{store_hash}/v3/channels

Request

Creates a Channel.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Content-Type in header with default of application/json - string - required
The MIME type of the request body.

Body

object | application/json

config_metaobject
Optional channel configuration object.
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). If false, the channel will not show in Channel Manager nor in any channels dropdown throughout the UI. Default value for this field is true if not specified on create.
statusstring
The status of the channel; channel type, platform, and status must be a valid combination. terminated is not valid for PUT or POST requests. deleted is not valid for POST requests.
Allowed: active | prelaunch | inactive | connected | disconnected | archived | deleted | terminated
namestring
required
Name of the channel as it will appear to merchants in the control panel.
typestring
required
The type of channel; channel platform and type must be a valid combination.
Allowed: pos | marketplace | storefront | marketing
platformstring
required
The name of the platform for the channel; channel platform and type must be a valid combination.

Create eBay Channel

{
  "name": "eBay",
  "platform": "ebay",
  "type": "marketplace",
  "status": "connected",
  "config_meta": {
    "app": {
      "id": 123,
      "sections": [
        {
          "title": "Overview",
          "query_path": "overview"
        },
        {
          "title": "Settings",
          "query_path": "settings"
        }
      ]
    }
  }
}

Response

Body

object | application/json

dataobject
metaobject
Response metadata.

response

{
  "data": {
    "id": 667159,
    "icon_url": "https://storage.googleapis.com/bigcommerce-production-dev-center/images/ebay_icon.png",
    "is_listable_from_ui": false,
    "is_visible": true,
    "date_created": "2021-05-13T15:41:39Z",
    "external_id": "",
    "config_meta": {
      "app": {
        "id": 123,
        "sections": [
          {
            "title": "Overview",
            "query_path": "overview"
          },
          {
            "title": "Settings",
            "query_path": "settings"
          }
        ]
      }
    },
    "type": "marketplace",
    "platform": "ebay",
    "date_modified": "2021-05-13T15:41:39Z",
    "name": "ebay",
    "status": "connected"
  },
  "meta": {}
}

Get a Channel

GET https://api.bigcommerce.com/stores/{store_hash}/v3/channels/{channel_id}

Request

Returns a Channel. Channel ID 1 returns the default BigCommerce storefront.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
include in query - string
Channels subresources that can be included in the response.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/channels/[channel_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

dataobject
metaobject
Response metadata.

response

{
  "data": {
    "id": 667159,
    "icon_url": "https://storage.googleapis.com/bigcommerce-production-dev-center/images/facebook_icon.svg",
    "is_listable_from_ui": false,
    "is_visible": true,
    "date_created": "2021-05-13T15:41:39Z",
    "external_id": "",
    "config_meta": {
      "app": {
        "id": 123,
        "sections": [
          {
            "title": "Overview",
            "query_path": "overview"
          },
          {
            "title": "Settings",
            "query_path": "settings"
          }
        ]
      }
    },
    "type": "marketplace",
    "platform": "facebook by meta",
    "date_modified": "2021-05-13T15:41:39Z",
    "name": "Facebook by Meta",
    "status": "connected",
    "currencies": {
      "channel_id": 667159,
      "enabled_currencies": [
        "USD"
      ],
      "default_currency": "USD"
    }
  },
  "meta": {}
}

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 and type cannot be updated after a channel is created.
A channel with status deleted or terminated cannot be updated.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Content-Type in header with default of application/json - string - required
The MIME type of the request body.

Body

object | application/json

config_metaobject
Optional channel configuration object.
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). If false, the channel will not show in Channel Manager nor in any channels dropdown throughout the UI. Default value for this field is true if not specified on create.
namestring
Name of the channel as it will appear to merchants in the control panel.
statusstring
The status of the channel; channel type, platform, and status must be a valid combination. terminated is not valid for PUT or POST requests. deleted is not valid for POST requests.
Allowed: active | prelaunch | inactive | connected | disconnected | archived | deleted | terminated

Update a Facebook by Meta Channel

{
  "name": "Facebook by Meta",
  "status": "connected",
  "is_listable_from_ui": false,
  "config_meta": {
    "app": {
      "id": 123,
      "sections": [
        {
          "title": "Overview",
          "query_path": "overview"
        },
        {
          "title": "Settings",
          "query_path": "settings"
        }
      ]
    }
  }
}

Response

Body

object | application/json

dataobject
metaobject
Response metadata.

response

{
  "data": {
    "id": 667159,
    "icon_url": "https://storage.googleapis.com/bigcommerce-production-dev-center/images/ebay_icon.png",
    "is_listable_from_ui": false,
    "is_visible": true,
    "date_created": "2021-05-13T15:41:39Z",
    "external_id": "",
    "config_meta": {
      "app": {
        "id": 123,
        "sections": [
          {
            "title": "Overview",
            "query_path": "overview"
          },
          {
            "title": "Settings",
            "query_path": "settings"
          }
        ]
      }
    },
    "type": "marketplace",
    "platform": "ebay",
    "date_modified": "2021-05-13T15:41:39Z",
    "name": "ebay",
    "status": "connected"
  },
  "meta": {}
}

Channels

Channels

Platform

Status

Warning

Channel listings

Channel site

Resources

Get All Channels

Request

Authentication

Parameters

example

Response

Body

dataarray[object]

metaobject

response

Create a Channel

Request

Authentication

Parameters

Body

config_metaobject

external_idstring

is_listable_from_uiboolean

is_visibleboolean

statusstring

namestringrequired

typestringrequired

platformstringrequired

Create eBay Channel

Response

Body

dataobject

metaobject

response

Get a Channel

Request

Authentication

Parameters

example

Response

Body

dataobject

metaobject

response

Update a Channel

Request

Updatable Fields

Note

Authentication

Parameters

Body

config_metaobject

external_idstring

is_listable_from_uiboolean

is_visibleboolean

namestring

statusstring

Update a Facebook by Meta Channel

Response

Body

dataobject

metaobject

response

namestring
required

typestring
required

platformstring
required