List Channel Listings

GET

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

GET

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

curl https://api.bigcommerce.com/stores/store_hash/v3/channels/1/listings \
     -H "Accept: application/json" \
     -H "X-Auth-Token: <apiKey>"

{
  "data": [
    {
      "channel_id": 667159,
      "listing_id": 882998595,
      "product_id": 80,
      "state": "active",
      "name": "Orbit Terrarium - Large",
      "description": "The same terrarium, but not a [Sample]",
      "date_created": "2021-05-24T17:46:33Z",
      "date_modified": "2021-05-24T17:46:33Z",
      "variants": [
        {
          "channel_id": 667159,
          "product_id": 80,
          "variant_id": 64,
          "state": "active",
          "name": "Terrarium with dinosaur",
          "date_created": "2021-05-24T17:46:33Z",
          "date_modified": "2021-05-24T17:46:33Z"
        },
        {
          "channel_id": 667159,
          "product_id": 80,
          "variant_id": 65,
          "state": "active",
          "name": "Terrarium with fish",
          "date_created": "2021-05-24T17:46:33Z",
          "date_modified": "2021-05-24T17:46:33Z"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "count": 1,
      "total": 1,
      "links": {
        "current": "?limit=1000"
      },
      "total_pages": 1
    }
  }
}

Returns a list of all 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 that if the Channel is not found or there is no listing associated with the Channel, it will return a 200 response with empty data.

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.

Query parameters

limitintegerOptional

Controls the number of items per page for paginated responses.

afterintegerOptional

Specifies the prior listing ID in a limited (paginated) list of listings.

product_id:inlist of longsOptional

Filter items by a comma-separated list of product IDs.

date_createdstringOptional

Filter items by date created. For example, date_created=2024-05-14T09:34:00 or date_created=2024-05-14.

date_created:minstringOptional

Filter items by minimum date created. For example, date_created=2024-05-14T09:34:00 or date_created=2024-05-14. Returns metafields created after this date.

date_created:maxstringOptional

Filter items by maximum date created. For example, date_created=2024-05-14T09:34:00 or date_created=2024-05-14. Returns metafields created before this date.

date_modifiedstringOptional

Filter items by date modified. For example, date_created=2024-05-14T09:34:00 or date_created=2024-05-14.

date_modified:minstringOptional

Filter items by minimum date modified. For example, date_created=2024-05-14T09:34:00 or date_created=2024-05-14. Returns metafields modified after this date.

date_modified:maxstringOptional

Filter items by maximum date modified. For example, date_created=2024-05-14T09:34:00 or date_created=2024-05-14. Returns metafields modified before this date.

Response

One or more channel listings.

datalist of objectsOptional

metaobjectOptional

Data about the response, including pagination.

Errors

400

Bad Request Error

422

Unprocessable Entity Error