Create Channel Listings

POST

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

POST

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

curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/channels/1/listings \
     -H "Accept: application/json" \
     -H "X-Auth-Token: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '[
  {
    "product_id": 80,
    "state": "active",
    "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"
      }
    ],
    "name": "Orbit Terrarium - Large",
    "description": "The same terrarium, but not a [Sample]"
  }
]'

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

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

Request

This endpoint expects a list of objects.

product_idlongRequired

The ID of the product associated with this channel listing.

stateenumRequired

The state of the product assignment or channel listing.

variantslist of objectsRequired

external_idstringOptional

Associated ID within a system / platform outside of BC.

namestringOptional

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.

descriptionstringOptional

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.

Response

One or more channel listings.

datalist of objectsOptional

metaobjectOptional

Data about the response, including pagination.

Errors

422

Unprocessable Entity Error