Create product listing pages

This is for:

Developer Merchandiser

In this article

Create a product listing page using the CMH
Create product listing pages in a batch

product listing pages (PLPs) let customers browse, filter, and sort products of a given category. They’re an integral part of any ecommerce implementation.

There are two ways to create PLPs:

If you only need to create a few pages, use the Coveo Merchandising Hub (CMH) to create them one by one.
To create multiple PLPs at once, use the Public Listing Page API to create them in a batch.

Create a product listing page using the CMH

You can create product listing pages (PLPs) directly in the Coveo Merchandising Hub (CMH).

To create a product listing page

In the CMH, select Product Listings.
In the header, select the Property and Locale for which you want to create a PLP, and then click Create listing page.
In the Page name field, enter a name for your PLP. The name you enter will appear in the Product listings manager, making it easy to identify and manage your PLP later.
In the Page URLs field, enter the full URL of your PLP, starting with https://. You can specify multiple URLs in this field.
Click Create page.
You’ll be prompted to create a filter rule for your product listing page (PLP). A PLP must contain at least one filter rule that defines the product category in which to display the products.

Once completed, your PLP will become active and appear in the Product listings manager.

Create product listing pages in a batch

To create one or more product listing pages (PLPs), make the following request to the Public Listing Page API:

POST https://platform.cloud.coveo.com/rest/organizations/<ORGANIZATION_ID>/commerce/v2/listings/pages/bulk-create HTTP/1.1

Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

where <ORGANIZATION_ID> is the unique identifier of your Coveo organization. To learn how to find your organization ID, see Find your organization ID.

Payload:

[
  {
    "name": "Canoes & Kayaks|Kayaks|Sports Kayaks", 
    "patterns": [ 
      {
        "url": "https://sports.barca.group/plp/canoes-kayaks/kayaks/sports-kayaks"
      }
    ],
    "pageRules": [ 
      {
        "name": "Include ec_category_slug contains canoes-kayaks/kayaks/sports-kayaks",
        "locales": [
          {
            "language": "en",
            "country": "US",
            "currency": "USD"
          }
        ],
        "filters": [
          {
            "fieldName": "ec_category_slug",
            "operator": "contains",
            "value": { 
              "type": "array",
              "values": [
                "canoes-kayaks/kayaks/sports-kayaks"
              ]
            }
          }
        ]
      }
    ],
    "trackingId": "barca_sports_ca" 
  }
]

	Specify the name of the PLP. This is also what appears in the CMH.
	Specify one or more URLs associated with the PLP. These URLs are used by the Commerce API on the front end to retrieve this PLP.
	Specify the filter rule that defines the PLP. Each PLP must be defined by at least one filter rule. In this example, the PLP filters products that belong to the category `canoes-kayaks/kayaks/sports-kayaks`.
	Set the properties of the `value` object to match its `type`. This example uses the `array` type, which carries its data in a `values` array. Other types use different property names: a `decimal` type takes a single numeric `value`, and a `range` type takes a `range` object. For example, to filter on a decimal field such as `ec_price`: `{ "fieldName": "ec_price", "operator": "isGreaterThan", "value": { "type": "decimal", "value": 200 } }` For every supported type and the property it expects, see Listing page rule value types.
	The `trackingId` lets you segregate your PLPs. When you make a request through the Commerce API to retrieve this PLP, you’ll need to specify the tracking ID.

Listing page rule value types

Each filter in a listing page rule pairs a field with an operator, and most operators also take a value. When you create a listing page in the Coveo Merchandising Hub (CMH), the interface selects the right rule value type for you. When you create listing pages through the Public Listing Page API, you specify the value type yourself in the value object’s type property, and the remaining properties of that object change depending on the type you choose.

Value types

The type property you choose determines which other property holds the value data, and that property name differs from one type to the next. The following table lists each type and the property it expects:

Value type type Value property Expects

Value type	`type`	Value property	Expects
Decimal	`decimal`	`value`	A JSON number, such as `200` or `99.99`. Don’t quote it and don’t wrap it in an array.
String	`string`	`value`	A single string of up to 255 characters.
Hierarchic multi	`hierarchicMultiValue`	`value`	A single string of up to 255 characters, holding one hierarchical path.
Multi string	`array`	`values`	An array of at least one string, each up to 255 characters.
Inclusive range	`range`	`range`	An object with `from` and `to` numbers. Both bounds are included in the range.

Decimal

decimal

value

A JSON number, such as 200 or 99.99. Don’t quote it and don’t wrap it in an array.

String

string

value

A single string of up to 255 characters.

Hierarchic multi

hierarchicMultiValue

value

A single string of up to 255 characters, holding one hierarchical path.

Multi string

array

values

An array of at least one string, each up to 255 characters.

Inclusive range

range

An object with from and to numbers. Both bounds are included in the range.

The isDefined and isNotDefined operators test only whether a field has a value at all. Omit the value object entirely when you use them.

Note

The Commerce API specification also lists a seed relative value type. It applies only to seeded recommendation slot rules.

Value type examples

A decimal value, filtering on price:

{
  "fieldName": "ec_price",
  "operator": "isGreaterThan",
  "value": {
    "type": "decimal",
    "value": 200
  }
}

A multi string value, filtering on category:

{
  "fieldName": "ec_category_slug",
  "operator": "contains",
  "value": {
    "type": "array",
    "values": [
      "canoes-kayaks/kayaks/sports-kayaks"
    ]
  }
}

An inclusive range value, filtering on stock:

{
  "fieldName": "ec_in_stock_quantity",
  "operator": "isBetween",
  "value": {
    "type": "range",
    "range": {
      "from": 1000,
      "to": 3000
    }
  }
}

Troubleshoot value type errors

A request that uses the wrong property name for its value type fails with a 422 response and the message Parameter 'value' must not be null. Despite the wording, the problem is usually the property name rather than a missing value.

For example, pairing "type": "decimal" with a values array returns this error, because a decimal value type expects the singular value property:

{
  "fieldName": "ec_price",
  "operator": "isGreaterThan",
  "value": {
    "type": "decimal",
    "values": [200]
  }
}

Check the type you specified against the Value types table and confirm you’re using the property name that type expects.