Update Channel Listings | BigCommerce Developer Center

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

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.

If a new variant is provided, the API will append the variant to the list. If a variant already exists, the API will update the existing variant. Other variants that are not provided in the payload remains unchanged.

If listing_id does not exist, the API will return a 200 response with empty data.

listing_id is required and cannot be less than or equal to zero.

product_id cannot be updated after a channel listing is created.

product_id of a variant must match the product_id of the channel listing.

Updates 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. > #### 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. > * If a new variant is provided, the API will append the variant to the list. If a variant already exists, the API will update the existing variant. Other variants that are not provided in the payload remains unchanged. > * If `listing_id` does not exist, the API will return a 200 response with empty data. > * `listing_id` is required and cannot be less than or equal to zero. > * `product_id` cannot be updated after a channel listing is created. > * `product_id` of a variant must match the `product_id` of the channel listing.

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.

listing_idlongRequired>=1

The ID of the channel listing that has been created, returned, or updated. In a 422 error, you may receive a response that references the group_id. The group_id in the Invalid Listing ID example refers to the listing_id. Please use listing_id instead of group_id in the request payload.

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	import requests
2
3	url = "https://api.bigcommerce.com/stores/store_hash/v3/channels/channel_id/listings"
4
5	payload = [
6	{
7	"listing_id": 882998595,
8	"product_id": 80,
9	"state": "active",
10	"variants": [
11	{
12	"product_id": 80,
13	"variant_id": 64,
14	"state": "active",
15	"name": "Terrarium with dinosaur"
16	}
17	],
18	"name": "Orbit Terrarium - Large"
19	}
20	]
21	headers = {
22	"X-Auth-Token": "<apiKey>",
23	"Content-Type": "application/json"
24	}
25
26	response = requests.put(url, json=payload, headers=headers)
27
28	print(response.json())

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	}