Malachyte Portal/Pages

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.

HeaderTypeDescription
x-api-keystringMalachyte API key
Content-Typestringapplication/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.

EndpointDescription
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

ParameterTypeRequiredDescription
category_idstringYesThe category or Shopify collection identifier to list/search products for.

Query Parameters

ParameterTypeRequiredDescription
pageintegerOptionalFor paginated results, the page number to retrieve (1-indexed).
sizeintegerOptionalFor paginated results, the number of items per page.

Request Body Fields

FieldTypeRequiredDescription
search_component_idstring (UUID)YesThe UUID of the search component configured in Malachyte that defines the search logic, strategy, and ranking rules. It's available via the portal.
visitor_idstringYesA 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.
querystringOptionalSearch query to filter products within the category.
kintegerConditionallyNumber of items to return. Required for Large-k mode or payload-driven pagination.
catalogintegerOptionalThe 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_filtersFilter[]OptionalList of Filter objects to apply during search / listing retrieval.
sort_orderstring (SortOrder)OptionalSort order to apply to the results. Default is "RECOMMENDED".
allow_empty_querybooleanOptionalWhether to return results when query is an empty string (for example, a standard category listing).
return_filtersbooleanOptionalWhether to return assigned filter values, search filter definitions, and facet options in the response. Defaults to true.
user_idstringOptionalThe 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:

FieldTypeRequiredDescription
keystring or string[]YesThe 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).
valuesarrayYesThe value or values to compare against.
comparisonstringNoThe comparison operator. Defaults to EQUAL. See Supported Comparison Operators.
jsonpathstringOnly for JSONPATHThe JSONPath expression. See JSONPath Filters.

Supported Comparison Operators

OperatorDescriptionExample Values / Usage
EQUALThe field matches any of the values. This is the default."key": "color", "values": ["Black", "Navy"]
CONTAINSWorks the same as EQUAL. For list fields like tags, a product matches if any of its values is in values."key": "tags", "values": ["summer"]
BETWEENThe field is between two values, including both ends. Pass exactly two values."key": "price", "values": [50.0, 200.0]
JSONPATHEvaluates a JSONPath expression against product data, for nested fields or combined conditionsSee 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 in key, in order.
  • target0, target1, and so on refer to the entries in values, 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 ValueDescription
RECOMMENDEDDefault relevance/ranking score computed by the strategy (Default)
A_ZAlphabetical (A to Z)
Z_AReverse Alphabetical (Z to A)
HIGH_LOWPrice: High to Low
LOW_HIGHPrice: Low to High
NEW_OLDRelease/Updated date: Newest to Oldest
OLD_NEWRelease/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 CodeDescriptionReason
400 Bad RequestMalformed requestMissing category_id in path or missing search_component_id in the request body.
401 UnauthorizedInvalid API keyThe x-api-key header is missing or wrong.
404 Not FoundNo results foundNo 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 EntityValidation errorInvalid request payload or parameter types.
500 Internal Server ErrorUnexpected errorAn unexpected error occurred on Malachyte's side. If it keeps happening, contact Malachyte.
503 Service UnavailableService unavailableMalachyte 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 page and size in the URL query parameters.
  • Do not include k in 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 k in 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.