Create Channel Listings

POST

https://api.bigcommerce.com/stores/:store_hash/v3/channels/:channel_id/listings

POST

/stores/:store_hash/v3/channels/:channel_id/listings

$ curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/channels/1/listings \
>      -H "Accept: application/json" \
>      -H "X-Auth-Token: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '[
>   {
>     "product_id": 80,
>     "state": "active",
>     "variants": [
>       {
>         "product_id": 80,
>         "variant_id": 64,
>         "state": "active",
>         "name": "Terrarium with dinosaur"
>       },
>       {
>         "product_id": 80,
>         "variant_id": 65,
>         "state": "active",
>         "name": "Terrarium with fish"
>       }
>     ],
>     "name": "Orbit Terrarium - Large",
>     "description": "The same terrarium, but not a [Sample]"
>   }
> ]'

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 }

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.

Create Channel Listings

POST

https://api.bigcommerce.com/stores/:store_hash/v3/channels/:channel_id/listings

POST

/stores/:store_hash/v3/channels/:channel_id/listings

$ curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/channels/1/listings \
>      -H "Accept: application/json" \
>      -H "X-Auth-Token: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '[
>   {
>     "product_id": 80,
>     "state": "active",
>     "variants": [
>       {
>         "product_id": 80,
>         "variant_id": 64,
>         "state": "active",
>         "name": "Terrarium with dinosaur"
>       },
>       {
>         "product_id": 80,
>         "variant_id": 65,
>         "state": "active",
>         "name": "Terrarium with fish"
>       }
>     ],
>     "name": "Orbit Terrarium - Large",
>     "description": "The same terrarium, but not a [Sample]"
>   }
> ]'

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 }

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](/developer/docs/overview/api-fundamentals/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-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/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_idlongRequired

The ID of a channel.

store_hashstringRequired

Permanent ID of the BigCommerce store.

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

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.

Path parameters

channel_idlongRequired

The ID of a channel.

store_hashstringRequired

Permanent ID of the BigCommerce store.

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

Create Channel Listings

Create Channel Listings

Authentication

Path parameters

Headers

Request

Response

Errors

Authentication

OAuth scopes

Authentication header

Further reading

Path parameters

Headers

Request

Response

Errors

OAuth scopes

Authentication header

Further reading

$	curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/channels/1/listings \
>	-H "Accept: application/json" \
>	-H "X-Auth-Token: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '[
>	{
>	"product_id": 80,
>	"state": "active",
>	"variants": [
>	{
>	"product_id": 80,
>	"variant_id": 64,
>	"state": "active",
>	"name": "Terrarium with dinosaur"
>	},
>	{
>	"product_id": 80,
>	"variant_id": 65,
>	"state": "active",
>	"name": "Terrarium with fish"
>	}
>	],
>	"name": "Orbit Terrarium - Large",
>	"description": "The same terrarium, but not a [Sample]"
>	}
>	]'

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	}