Listings
Get Channel Listings
GET https://api.bigcommerce.com/stores/{store_hash}/v3/channels/{channel_id}/listingsRequest
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 headerrequired
Parameters
- store_hash in path - string
example
Response
Body
dataarray[object]
Single Listing
Multiple Listings
Create Channel Listings
POST https://api.bigcommerce.com/stores/{store_hash}/v3/channels/{channel_id}/listingsRequest
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 headerrequired
Parameters
- store_hash in path - string
Body
product_idinteger
requiredThe ID of the product associated with this channel listing.
external_idstring
Associated ID within a system / platform outside of BC.
statestring
requiredThe state of the product assignment or channel listing.
Allowed: active | disabled | error | pending | pending_disable | pending_delete | partially_rejected | queued | rejected | submitted | deleted
namestring
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.
descriptionstring
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.
variantsarray[object]
required
Create Single Listing
Create Multiple Listings
Response
Body
dataarray[object]
Single Listing
Multiple Listings
Update Channel Listings
PUT https://api.bigcommerce.com/stores/{store_hash}/v3/channels/{channel_id}/listingsRequest
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 theproduct_id
of the channel listing.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
Body
listing_idinteger
requiredThe 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
. Thegroup_id
in the Invalid Listing ID example refers to thelisting_id
. Please uselisting_id
instead ofgroup_id
in the request payload.Min: 1product_idinteger
requiredThe ID of the product associated with this channel listing.
external_idstring
Associated ID within a system / platform outside of BC.
statestring
requiredThe state of the product assignment or channel listing.
Allowed: active | disabled | error | pending | pending_disable | pending_delete | partially_rejected | queued | rejected | submitted | deleted
namestring
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.
descriptionstring
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.
variantsarray[object]
required
Update Single Listing
Update Multiple Listings
Response
Body
dataarray[object]
Single Listing
Multiple Listings
Get a Channel Listing
GET https://api.bigcommerce.com/stores/{store_hash}/v3/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 headerrequired
Parameters
- store_hash in path - string
example
Response
Body
dataobject