PLP API
API reference for the Product Listing Pages Engine
Purpose
The PLP API powers collection-based product listing pages while supporting:
- Accurate attribution across views, clicks, and conversions with background engagement logging
- Category-scoped listing & search allowing default category browsing or in-category keyword searches
- Dynamic filtering & sorting directly in the listing request
- Flexible retrieval via single large-k retrieval, payload-driven pagination, or query-driven pagination / infinite scroll
- Frontend-driven execution with backend-managed intelligence and component strategy resolution
- Collection-governed behavior with merchandising rules and pinning
Authentication
Every request must include the API key in the request header.
| Header | Type | Description |
|---|---|---|
x-api-key | string | Malachyte API key |
Content-Type | string | application/json |
Base URL: https://api-yoursite.malachyte.com (the client's Malachyte contact provides the exact URL for each store).
Limits: There are no rate limits today. Each request has a 1-second time limit by default, so very large k values may not return in time.
Core Endpoints
PLP runtime behavior mirrors Malachyte Search's endpoint pattern, but is collection-governed and routed through PLP-specific endpoints.
| Endpoint | Description |
|---|---|
POST /v1/listing/{category_id} | Lists or searches products for a given category/collection with optional filters, sort order, and pagination |
POST /v1/listing/{category_id}
Lists products for a given category.
By default, the endpoint queries all results for the specified category. If a query string is provided in the request body, it returns products in that category matching the string after executing data retrieval, pre-search category filtering, scoring, and sequencing operations. Filters and sort order can be applied directly in the request payload. The endpoint also asynchronously logs engagement views and impressions in the background.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
category_id | string | Yes | The category or Shopify collection identifier to list/search products for. |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | Optional | For paginated results, the page number to retrieve (1-indexed). |
size | integer | Optional | For paginated results, the number of items per page. |
Request Body Fields
| Field | Type | Required | Description |
|---|---|---|---|
search_component_id | string (UUID) | Yes | The UUID of the search component configured in Malachyte that defines the search logic, strategy, and ranking rules. It's available via the portal. |
visitor_id | string | Yes | A unique ID for the shopper's browser. On Shopify stores, it's generated automatically. On headless stores, the client sets it up on their side: generate one (for example, a UUID), store it in localStorage so it stays the same across visits, and send the same ID in pixel events. See Headless. |
query | string | Optional | Search query to filter products within the category. |
k | integer | Conditionally | Number of items to return. Required for Large-k mode or payload-driven pagination. |
catalog | integer | Optional | The catalog identifier. Only needed if the store has more than one catalog (for example, two storefronts or brands under one Malachyte account). Defaults to -1 when left out. The client's Malachyte contact provides the value. |
search_filters | Filter[] | Optional | List of Filter objects to apply during search / listing retrieval. |
sort_order | string (SortOrder) | Optional | Sort order to apply to the results. Default is "RECOMMENDED". |
allow_empty_query | boolean | Optional | Whether to return results when query is an empty string (for example, a standard category listing). |
return_filters | boolean | Optional | Whether to return assigned filter values, search filter definitions, and facet options in the response. Defaults to true. |
user_id | string | Optional | The unique identifier of the logged-in shopper. It stays the same across sessions. Leave blank if the shopper isn't logged in. |
Filtering in the Listing Request
Structured filters can be passed directly to POST /v1/listing/{category_id} via search_filters.
Filter Object Structure
Each filter object conforms to the following schema:
| Field | Type | Required | Description |
|---|---|---|---|
key | string or string[] | Yes | The product field to filter on (for example, color or price). For JSONPATH, the field name or names the expression refers to, in order (key0, key1, and so on). |
values | array | Yes | The value or values to compare against. |
comparison | string | No | The comparison operator. Defaults to EQUAL. See Supported Comparison Operators. |
jsonpath | string | Only for JSONPATH | The JSONPath expression. See JSONPath Filters. |
Supported Comparison Operators
| Operator | Description | Example Values / Usage |
|---|---|---|
EQUAL | The field matches any of the values. This is the default. | "key": "color", "values": ["Black", "Navy"] |
CONTAINS | Works the same as EQUAL. For list fields like tags, a product matches if any of its values is in values. | "key": "tags", "values": ["summer"] |
BETWEEN | The field is between two values, including both ends. Pass exactly two values. | "key": "price", "values": [50.0, 200.0] |
JSONPATH | Evaluates a JSONPath expression against product data, for nested fields or combined conditions | See JSONPath Filters |
JSONPath Filters
JSONPath filters can look inside nested product data (for example, variant prices) and combine several conditions in one filter.
A JSONPath filter uses placeholders instead of real field names and values:
key0,key1, and so on refer to the field names inkey, in order.target0,target1, and so on refer to the entries invalues, in order.
Products tagged sale:
{
"key": "tags",
"values": ["sale"],
"comparison": "JSONPATH",
"jsonpath": "$[?(@.key0[?(@ == target0)])]"
}Products with any variant priced under 40:
{
"key": ["variants", "price"],
"values": [40],
"comparison": "JSONPATH",
"jsonpath": "$..key0[?(@.key1 < target0)]"
}Exclude products tagged hide-product:
{
"key": "tags",
"values": ["hide-product"],
"comparison": "JSONPATH",
"jsonpath": "$[?((!@.key0[?(@ == target0)]))]"
}Products tagged sale or clearance, with any variant priced under 40:
{
"key": ["tags", "variants", "price"],
"values": ["sale", "clearance", 40],
"comparison": "JSONPATH",
"jsonpath": "$[?((@.key0[?(@ == target0)] || @.key0[?(@ == target1)]) && @.key1[?(@.key2 < target2)])]"
}Note
Text values must match the casing used in the product data (for example, Sale and sale are treated as different tags).
Supported Sort Orders
| Sort Value | Description |
|---|---|
RECOMMENDED | Default relevance/ranking score computed by the strategy (Default) |
A_Z | Alphabetical (A to Z) |
Z_A | Reverse Alphabetical (Z to A) |
HIGH_LOW | Price: High to Low |
LOW_HIGH | Price: Low to High |
NEW_OLD | Release/Updated date: Newest to Oldest |
OLD_NEW | Release/Updated date: Oldest to Newest |
Example Requests
1. Category Listing with Filters and Sort Order
Retrieve products in a collection filtered by color and price range, sorted by price low to high:
POST /v1/listing/123456789
{
"search_component_id": "7b6c5432-e89b-12d3-a456-426614174000",
"visitor_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"k": 24,
"sort_order": "LOW_HIGH",
"search_filters": [
{
"key": "color",
"values": ["Black", "Navy"],
"comparison": "EQUAL"
},
{
"key": "price",
"values": [50.0, 200.0],
"comparison": "BETWEEN"
}
],
"return_filters": true
}2. Category Listing with a Size Filter
List all products in collection "123456789" by passing an empty query, filtered by size:
POST /v1/listing/123456789
{
"search_component_id": "7b6c5432-e89b-12d3-a456-426614174000",
"visitor_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"query": "",
"k": 24,
"search_filters": [
{
"key": "size",
"values": ["L", "XL"],
"comparison": "EQUAL"
}
]
}3. Paginated Request with Filters
POST /v1/listing/123456789?page=2&size=24
{
"search_component_id": "7b6c5432-e89b-12d3-a456-426614174000",
"visitor_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"search_filters": [
{
"key": "color",
"values": ["Black"],
"comparison": "EQUAL"
}
]
}Response
When return_filters=true, the response includes product results, merchandising metadata, and available filter facet statistics:
The fields inside facts depend on the client's setup, so field names (for example, id or product_id) vary by store. The examples here are only examples.
{
"strategy_name": "plp",
"total_results": 42,
"results": [
{
"score": 0.94,
"facts": {
"id": "1001",
"title": "Classic Cotton Blazer",
"price": 120.0,
"color": "Black",
"size": "L"
}
}
],
"assigned_filter_values": {
"color": ["Black", "Navy"],
"price": [50.0, 200.0]
},
"options": [
{
"key": "color",
"values_w_stats": {
"Black": 24,
"Navy": 18,
"White": 12
},
"assigned_filter_values": ["Black", "Navy"]
},
{
"key": "size",
"values_w_stats": {
"S": 10,
"M": 22,
"L": 19,
"XL": 8
},
"assigned_filter_values": []
}
]
}Banners
The response returns products only. Banners set up in Shopify (plp_banner MetaObjects) are not included. Headless storefronts fetch banners from Shopify directly and place them in the product grid themselves.
Error Responses
Errors return the matching HTTP status code and a JSON body with a detail message:
{
"detail": "No search results found: All candidates filtered, try loosening filter criteria."
}| Status Code | Description | Reason |
|---|---|---|
400 Bad Request | Malformed request | Missing category_id in path or missing search_component_id in the request body. |
401 Unauthorized | Invalid API key | The x-api-key header is missing or wrong. |
404 Not Found | No results found | No matching products were found, the category_id doesn't exist, or all results were filtered out ("No search results found: All candidates filtered, try loosening filter criteria."). |
422 Unprocessable Entity | Validation error | Invalid request payload or parameter types. |
500 Internal Server Error | Unexpected error | An unexpected error occurred on Malachyte's side. If it keeps happening, contact Malachyte. |
503 Service Unavailable | Service unavailable | Malachyte couldn't process the request right now. Retry the request; if the error persists, contact Malachyte. |
Note
A 404 means the request was valid but there were no products to show. Treat it as an empty result (for example, show a "No products found" message) rather than as a failure.
Pagination & Infinite Scroll
Product Listing Pages support flexible retrieval modes matching the Search workflow:
First Request (Choose One)
Option A — Query-driven
- Include
pageandsizein the URL query parameters. - Do not include
kin the request body.
POST /v1/listing/123456789?page=1&size=24
{
"search_component_id": "7b6c5432-e89b-12d3-a456-426614174000",
"visitor_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}Option B — Payload-driven
- Pass
kin the request body. - Do not include query parameters in the URL.
POST /v1/listing/123456789
{
"search_component_id": "7b6c5432-e89b-12d3-a456-426614174000",
"visitor_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"k": 24
}Subsequent Requests
For infinite scroll or subsequent pages, pass page and size query parameters:
POST /v1/listing/123456789?page=2&size=24
{
"search_component_id": "7b6c5432-e89b-12d3-a456-426614174000",
"visitor_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}Subsequent page requests retrieve additional slices of the same shaped dataset. Pinning and ranking are already applied and remain consistent across pages.
Attribution & Identity
Tip
Data Integrity & Tracking These fields are essential for measuring PLP performance and ROI.
visitor_id: a unique ID for the shopper's browser. On Shopify stores, it's generated automatically. On headless stores, the client sets it up on their side. Use the same ID that's sent in pixel events.user_id— Identifies a logged-in shopper and stays the same across sessions.