Recommendations API

Purpose

The Recommendations API returns a ranked list of products for a recommendation component enabled in the Malachyte Portal. It supports:

Component-driven behavior: the strategy, rules, filters, and ranking all come from the component in the Portal, so what shoppers see can be changed without frontend code changes.
Personalization and attribution: a required visitor_id (one shopper session) and an optional user_id (a logged-in shopper, across sessions) tie recommendations, clicks, and conversions together.
Frontend-driven execution: the client's storefront calls the API directly at runtime.

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

Core Endpoints

Endpoint	Description
POST `/v1/recommendations/component`	Returns recommended products for a given recommendation component

`POST /v1/recommendations/component`

Request Body Fields

Field	Type	Required	Description
`component_id`	string (UUID)	Yes	The ID of the recommendation component created in the Malachyte Portal. It determines the strategy, filters, and ranking logic.
`query`	string	Yes	The context for the recommendation. For product-page recommendations, this is usually the Shopify product ID. Depending on the component type, it can also be another ID, such as a collection ID.
`visitor_id`	string (UUID)	Yes	Identifier for the shopper's current session, used for personalization and attribution. Keep it the same for the whole session.
`user_id`	string	Optional	The unique identifier of the logged-in shopper. It stays the same across sessions. Should be left blank if the shopper isn't logged in.
`k`	integer	Optional	The number of recommended products to return. A default is used if it's left out.
`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). Leave it out otherwise. The client's Malachyte contact provides the value.
`exclusions`	string[]	Optional	Product IDs to exclude from the results.

Example Request

curl --location 'https://api-yoursite.malachyte.com/v1/recommendations/component' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"component_id": "aaa-bbb-ccc-ddd-eee",
"query": "123456",
"visitor_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"user_id": "cde456",
"k": 6
}'

Example Response

{
  "strategy_name": "recommended-for-you",
  "results": [
    {
      "score": 0.47,
      "facts": {
        "product_id": 123456,
        "name": "Classic Cotton Blazer",
        "image": "https://cdn.yourstore.com/products/classic-cotton-blazer.jpg",
        "relative_url": "/products/classic-cotton-blazer",
        "price": 120.0,
        "sale_price": 99.0
      }
    }
  ]
}

strategy_name: the strategy behind the component.
results: the recommended products, in ranked order. Each has a score and its product data in facts.
facts: comes from the client's product catalog, so the fields vary by store.

Status Code	Description	Reason
`400 Bad Request`	Unknown component	The `component_id` doesn't match a component in the Portal (`"Unknown Component: <id>"`).
`400 Bad Request`	Malformed request	`query` is missing (`"Malformed request: query missing"`), or both `user_id` and `visitor_id` are missing (`"Malformed request: user_id and visitor_id missing"`).
`404 Not Found`	No recommendations found	No candidate products were found (`"No recommendations found: No candidates returned."`), or the component's filters removed all of them (`"No recommendations found: All candidates filtered, try loosening filter criteria."`).
`422 Unprocessable Entity`	Validation error	A field has the wrong type.
`500 Internal Server Error`	Unexpected error	An unexpected error occurred on Malachyte's side. If it keeps happening, contact Malachyte.
`503 Service Unavailable`	Internal error	Something went wrong on Malachyte's side while processing the request. The request can be retried; if the error persists, contact Malachyte.

A 404 means the request was valid but there were no products to recommend. The storefront should treat it as an empty result (for example, by hiding the recommendation widget) rather than as a failure.

Behavior Notes

Strategy ownership: everything about how results are chosen and ordered (strategy, boosts, filters, ranking) is controlled by the component_id. See Components and Rules.
Flexible context: the query field can represent different things depending on the component type (for example, a product ID or a collection ID).

Attribution & Identity

Tip

Data Integrity & Tracking These fields are essential for measuring recommendation performance and ROI.

visitor_id: a UUID that identifies the shopper's current session. It must stay the same for the whole session for personalization and attribution to work.
user_id: identifies a logged-in shopper and stays the same across sessions.

Testing in the Playground

A component's results can be previewed in the Portal before going live. See Playground.