Docs
Management API
Channels
Listings

Listings

Get Channel Listings

GET /channels/{channel_id}/listings

Request

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-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • channel_id in path - integer
    required
    The ID of a channel.
  • limit in query - integer
    Controls the number of items per page for paginated responses.
  • after in query - integer
    Specifies the prior listing ID in a limited (paginated) list of listings.
  • product_id:in in query - array
    Filter items by a comma-separated list of product IDs.
    Type: array[integer]
  • date_created in query - string
    Filter items by date created. For example, date_created=2024-05-14T09:34:00 or date_created=2024-05-14.
  • date_created:min in query - string
    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:max in query - string
    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_modified in query - string
    Filter items by date modified. For example, date_created=2024-05-14T09:34:00 or date_created=2024-05-14.
  • date_modified:min in query - string
    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:max in query - string
    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.

example

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/channels/[channel_id]/listings' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination.

Single Listing

{
"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,

Multiple Listings

{
"data": [
{
"channel_id": 664177,
"listing_id": 882789361,
"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": 664177,
"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": 664177,
"product_id": 80,

Create Channel Listings

POST /channels/{channel_id}/listings

Request

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

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • channel_id in path - integer
    required
    The ID of a channel.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

array | application/json

  • product_id    integer
    required

    The ID of the product associated with this channel listing.

  • external_id    string

    Associated ID within a system / platform outside of BC.

  • state    string
    required

    The state of the product assignment or channel listing.

    Allowed: active | disabled | error | pending | pending_disable | pending_delete | partially_rejected | queued | rejected | submitted | deleted

  • name    string

    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.

  • description    string

    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.

  • variants    array[object]
    required

Create Single Listing

[
{
"product_id": 80,
"state": "active",
"name": "Orbit Terrarium - Large",
"description": "The same terrarium, but not a [Sample]",
"variants": [
{
"product_id": 80,
"variant_id": 64,
"state": "active",
"name": "Terrarium with dinosaur"
},
{
"product_id": 80,
"variant_id": 65,
"state": "active",
"name": "Terrarium with fish"
}
]
}
]

Create Multiple Listings

[
{
"product_id": 80,
"state": "active",
"name": "Orbit Terrarium - Large",
"description": "The same terrarium, but not a [Sample]",
"variants": [
{
"product_id": 80,
"variant_id": 64,
"state": "active",
"name": "Terrarium with dinosaur"
},
{
"product_id": 80,
"variant_id": 65,
"state": "active",
"name": "Terrarium with fish"
}
]
},
{
"product_id": 100,
"state": "pending",
"name": "Womenʼs Bold T-Shirt",
"description": "The same t-shirt, but not a [Sample]",
"variants": [
{
"product_id": 100,

Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination.

Single Listing

{
"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,

Multiple Listings

{
"data": [
{
"channel_id": 664177,
"listing_id": 882789361,
"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": 664177,
"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": 664177,
"product_id": 80,

Update Channel Listings

PUT /channels/{channel_id}/listings

Request

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-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • channel_id in path - integer
    required
    The ID of a channel.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

array | application/json

  • listing_id    integer
    required

    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.
    Min: 1

  • product_id    integer
    required

    The ID of the product associated with this channel listing.

  • external_id    string

    Associated ID within a system / platform outside of BC.

  • state    string
    required

    The state of the product assignment or channel listing.

    Allowed: active | disabled | error | pending | pending_disable | pending_delete | partially_rejected | queued | rejected | submitted | deleted

  • name    string

    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.

  • description    string

    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.

  • variants    array[object]
    required

Update Single Listing

[
{
"listing_id": 882998595,
"product_id": 80,
"state": "active",
"name": "Orbit Terrarium - Large",
"variants": [
{
"product_id": 80,
"variant_id": 64,
"state": "active",
"name": "Terrarium with dinosaur"
}
]
}
]

Update Multiple Listings

[
{
"listing_id": 882789361,
"product_id": 80,
"state": "active",
"name": "Orbit Terrarium - Large",
"variants": [
{
"product_id": 80,
"variant_id": 64,
"state": "active",
"name": "Terrarium with dinosaur"
}
]
},
{
"listing_id": 882789362,
"product_id": 100,
"state": "pending",
"name": "Womenʼs Bold T-Shirt",
"variants": [
{
"product_id": 100,
"variant_id": 91,
"state": "pending",
"name": "Small womenʼs bold t-shirt"
}
]
}
]

Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination.

Single Listing

{
"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,

Multiple Listings

{
"data": [
{
"channel_id": 664177,
"listing_id": 882789361,
"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": 664177,
"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": 664177,
"product_id": 80,

Get a Channel Listing

GET /channels/{channel_id}/listings/{listing_id}

Request

Returns a Channel Listing for a specific channel. We recommend using this endpoint for non-storefront channels like marketplaces, marketing channels, and point of sale (POS) channels.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • channel_id in path - integer
    required
    The ID of a channel.
  • listing_id in path - integer
    required
    The ID of a channel listing.

example

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/channels/[channel_id]/listings/[listing_id]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json

  • data    object

  • meta    object

    Response metadata.

response

{
"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",
Did you find what you were looking for?
Delete Channel Currency AssignmentsGet Channel Listings