Update Channel Listings

PUT

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

PUT

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

$ curl -X PUT 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 '[
>   {
>     "listing_id": 882998595,
>     "product_id": 80,
>     "state": "active",
>     "variants": [
>       {
>         "product_id": 80,
>         "variant_id": 64,
>         "state": "active",
>         "name": "Terrarium with dinosaur"
>       }
>     ],
>     "name": "Orbit Terrarium - Large"
>   }
> ]'

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 }

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

Response

datalist of objects

metaobject

Data about the response, including pagination.

Errors

422

Unprocessable Entity Error

Note

Authentication

OAuth scopes

Authentication header

Further reading

Path parameters

Headers

Request

Response

Errors

Note

OAuth scopes

Authentication header

Further reading