Docs
Management API
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
    required

Parameters

  • store_hash in path - string
  • 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

Response

Body

object | application/json
  • data
    array[object]

  • meta
    object

    Data about the response, including pagination.

Single Listing

Multiple Listings

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
    required

Parameters

  • store_hash in path - string
  • 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

Create Multiple Listings

Response

Body

object | application/json
  • data
    array[object]

  • meta
    object

    Data about the response, including pagination.

Single Listing

Multiple Listings

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
    required

Parameters

  • store_hash in path - string
  • 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

Update Multiple Listings

Response

Body

object | application/json
  • data
    array[object]

  • meta
    object

    Data about the response, including pagination.

Single Listing

Multiple Listings

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
    required

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

Response

Body

object | application/json
  • data
    object

  • meta
    object

    Response metadata.

response

Did you find what you were looking for?