List Channel Listings | BigCommerce Developer Center

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.

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

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

datalist of objects

metaobject

Data about the response, including pagination.

Errors

400

Bad Request Error

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	{
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	}

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