Get Started

Headless

Integrate Malachyte with a headless system

This guide is the starting point for integrating Malachyte with a headless or custom-built storefront. It covers what is needed before starting and links to the full API reference for each product.

Overview

Malachyte powers personalized recommendations, search, and product listing pages (PLP) for e-commerce platforms. Malachyte supports both Shopify and custom-built websites.

In a headless setup, the client's storefront calls the Malachyte API directly at runtime. The logic (strategy, rules, filters, ranking) lives in components set up in the Malachyte Portal, so clients can change what shoppers see without changing frontend code.


Before Starting

Requirements:

  • An API key. Every request sends it in the x-api-key header. The key is restricted and Malachyte's endpoints don't return sensitive data, so it can be used in storefront (browser) code. The client's Malachyte contact provides it.
  • A base URL. It looks like https://api-yoursite.malachyte.com. The client's Malachyte contact provides the exact URL for each store.
  • Component IDs from the Portal. Each recommendation, search, or PLP experience is a component in the Malachyte Portal with its own ID.
  • A visitor_id. A unique ID for the shopper's browser (for example, a UUID). Generate it once and store it in localStorage so it stays the same across visits, and send the same ID in pixel events. It drives personalization and attribution. If the shopper is logged in, also send their user_id, which stays the same across sessions.
  • A product catalog import. For headless stores outside the Shopify ecosystem, there's no fixed file format. Malachyte adapts to the client's existing product export. Clients usually upload files to a Malachyte Google Cloud Storage bucket, and the catalog syncs once a day. Missing fields won't break the import, but recommendations work best with at least: product ID, title, description, product image and tags. For PLPs, also include a category field (see Defining Categories).

Full authentication details are on each API page below.


API Reference by Product

ProductMain endpointFull reference
RecommendationsPOST /v1/recommendations/componentRecommendations API
SearchPOST /v1/search/componentSearch API
Product Listing Pages (PLP)POST /v1/listing/{category_id}PLP API

Each page covers authentication, request fields, example requests, error responses, and behavior notes for that product.