For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dev Portal
DocsAPI ReferenceLearnCommunityChangelog
DocsAPI ReferenceLearnCommunityChangelog
    • About Our APIs
  • REST
    • Overview
      • Overview
        • Abandoned Carts
        • Carts
        • Channels
            • GETList Channels
            • POSTCreate Channel
            • GETGet Channel
            • PUTUpdate Channel
              • GETList Channel Listings
              • POSTCreate Channel Listings
              • PUTUpdate Channel Listings
              • GETGet Channel Listing
        • Checkouts
        • Currencies
        • Customer Segmentation
        • Geography
        • Infrastructure Hosting
        • Inventory
        • Orders
        • Order Operations
        • Pickup
        • Pickup Methods
        • Pickup Options
        • Pricing
        • Price Lists
        • Promotions
        • Promotion Settings
        • Redirects
        • Scripts
        • Settings
        • Shipping
        • Sites
        • Subscribers
        • System Logs
        • Tax
        • Wishlists
      • Payments
  • GraphQL
    • Overview
  • MCP
    • Overview
Dev Portal
LogoLogo
RESTAdminManagementChannelsListings

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.
Was this page helpful?
Previous

Create Channel Listings

Next

Get Channel Listing

Built with

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](/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.

Headers

AcceptstringRequiredDefaults to application/json
The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.

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 NamePermissionParameter
Channel Listingsmodifystore_channel_listings
Channel Listingsread-onlystore_channel_listings_read_only
Channel Settingsmodifystore_channel_settings
Channel Settingsread-onlystore_channel_settings_read_only
Sites & Routesmodifystore_sites
Sites & Routesread-onlystore_sites_read_only

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access_tokens, see our Guide to API Accounts.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see our Guide to API Accounts.

For a list of API status codes, see API Status Codes.

The MIME type of the response body.