Malachyte Headless Site Technical Integration Guide

This guide outlines how to integrate with Malachyte’s recommendation and search platform, including API usage, onboarding flow, data sync methods, and merchandising tooling.

Overview

Malachyte powers personalized recommendations and search for e-commerce platforms. We support both Shopify and custom-built websites.

This document covers:

API integration for recommendations and search
Setup and onboarding
Data format and syncing
Portal features for merchandising teams

Malachyte supports component-based recommendation APIs executed directly from the frontend. Each component encapsulates a fully configured strategy—including ranking logic, filters, and boosts—defined in the Malachyte portal and invoked via API at runtime.

This endpoint returns a list of recommended products for a given component configuration, allowing teams to deploy, test, and iterate on experiences without frontend logic changes.

Endpoint

POST /v1/recommendations/component

Authentication

All requests must include an API key passed via the header.

Header	Type	Description
`x-api-key`	`string`	Your Malachyte API key
`Content-Type`	`string`	`application/json`

Example Request

curl --location '[https://api-shopify-staging.malachyte.dev/v1/recommendations/component](https://api-shopify-staging.malachyte.dev/v1/recommendations/component)' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "component_id": "4257e7a9-05f3-46d4-a536-13bff2037a89",
  "query": "7451049984134",
  "catalog": "-1",
  "log_response": true,
  "from_portal": false,
  "visitor_id": "bdf48c2b-a144-4497-b571-3a12012cf92c",
  "k": 6
}'

Request Body

All fields are required.

Field	Type	Description
component_id	`string (UUID)`	Unique identifier for the recommendation component, generated in the Malachyte portal. Determines the strategy, filters, and ranking logic applied.
query	`string`	The primary query context. For product-based recommendations, this is typically a Shopify product ID.
catalog	`string`	Internal catalog identifier associated with the customer’s Shopify store. Used to scope recommendations to the correct dataset.
log_response	`boolean`	Whether the full recommendation response should be logged for debugging or analysis purposes.
from_portal	`boolean`	Indicates whether the request originated from a portal-configured component. Used for internal routing and analytics.
visitor_id	`string`	Anonymous or authenticated visitor identifier. Used for personalization, session continuity, and attribution.
k	`number`	The number of recommended items to return.

Behavior Notes

Strategy Ownership: The component configuration (strategy, boosts, filters, ranking) is entirely driven by the component_id.
User Persistence: visitor_id enables user-level personalization and attribution across sessions; this must persist across the entire user session.
Flexible Context: The query field may represent different entities depending on the component type (e.g., Product ID, Collection ID).
Validation: Requests missing any required field will return a validation error (typically a 422 Unprocessable Entity).

Headless