Create Channel Listings | BigCommerce Developer Center

Creates one or more Channel Listings for a specific channel. We recommend using this endpoint for non-storefront channels like marketplaces, marketing channels, and point of sale (POS) channels.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI Name	Permission	Parameter
Channel Listings	modify	`store_channel_listings`
Channel Listings	read-only	`store_channel_listings_read_only`
Channel Settings	modify	`store_channel_settings`
Channel Settings	read-only	`store_channel_settings_read_only`
Sites & Routes	modify	`store_sites`
Sites & Routes	read-only	`store_sites_read_only`

Authentication header

Header	Argument	Description
`X-Auth-Token`	`access_token`	For more about API accounts that generate `access_token`s, see our Guide to API Accounts.

### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Channel Listings | modify | `store_channel_listings` | | Channel Listings | read-only | `store_channel_listings_read_only` | | Channel Settings | modify | `store_channel_settings` | | Channel Settings | read-only | `store_channel_settings_read_only` | | Sites & Routes | modify | `store_sites` | | Sites & Routes | read-only | `store_sites_read_only` | ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

Path parameters

channel_idstringRequired

Request

This endpoint expects a list of objects.

product_idlongRequired

The ID of the product associated with this channel listing.

stateenumRequired

The state of the product assignment or channel listing.

variantslist of objectsRequired

external_idstringOptional

Associated ID within a system / platform outside of BC.

namestringOptional

Name of the product for this channel listing specifically. This is an optional field that can be used to override the product name in the catalog.

descriptionstringOptional

Description of the product for this channel listing specifically. This is an optional field that can be used to override the product description in the catalog.

Response

datalist of objects

metaobject

Data about the response, including pagination.

Errors

422

Unprocessable Entity Error

OAuth scopes

UI Name	Permission	Parameter
Channel Listings	modify	`store_channel_listings`
Channel Listings	read-only	`store_channel_listings_read_only`
Channel Settings	modify	`store_channel_settings`
Channel Settings	read-only	`store_channel_settings_read_only`
Sites & Routes	modify	`store_sites`
Sites & Routes	read-only	`store_sites_read_only`

Authentication header

Header	Argument	Description
`X-Auth-Token`	`access_token`	For more about API accounts that generate `access_token`s, see our Guide to API Accounts.

1	curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/channels/channel_id/listings \
2	-H "X-Auth-Token: <apiKey>" \
3	-H "Content-Type: application/json" \
4	-d '[
5	{
6	"product_id": 80,
7	"state": "active",
8	"variants": [
9	{
10	"product_id": 80,
11	"variant_id": 64,
12	"state": "active",
13	"name": "Terrarium with dinosaur"
14	},
15	{
16	"product_id": 80,
17	"variant_id": 65,
18	"state": "active",
19	"name": "Terrarium with fish"
20	}
21	],
22	"name": "Orbit Terrarium - Large",
23	"description": "The same terrarium, but not a [Sample]"
24	}
25	]'

1	{
2	"data": [
3	{
4	"channel_id": 667159,
5	"listing_id": 882998595,
6	"product_id": 80,
7	"state": "active",
8	"name": "Orbit Terrarium - Large",
9	"description": "The same terrarium, but not a [Sample]",
10	"date_created": "2021-05-24T17:46:33Z",
11	"date_modified": "2021-05-24T17:46:33Z",
12	"variants": [
13	{
14	"channel_id": 667159,
15	"product_id": 80,
16	"variant_id": 64,
17	"state": "active",
18	"name": "Terrarium with dinosaur",
19	"date_created": "2021-05-24T17:46:33Z",
20	"date_modified": "2021-05-24T17:46:33Z"
21	},
22	{
23	"channel_id": 667159,
24	"product_id": 80,
25	"variant_id": 65,
26	"state": "active",
27	"name": "Terrarium with fish",
28	"date_created": "2021-05-24T17:46:33Z",
29	"date_modified": "2021-05-24T17:46:33Z"
30	}
31	]
32	}
33	],
34	"meta": {
35	"pagination": {
36	"count": 1,
37	"total": 1,
38	"links": {
39	"current": "?limit=1000"
40	},
41	"total_pages": 1
42	}
43	}
44	}