Malachyte Portal/Pages

Defining Categories

How categories work for Shopify and headless stores

What is a category?

A category is the group of products a Product Listing Page (PLP) shows, for example "Men's Boots" or "New Arrivals". It is passed as the {category_id} in the PLP (listing) endpoint:

POST /v1/listing/{category_id}

Each category corresponds to a Page in the Malachyte Portal, where merchandising rules, pinning, filters, and banners are configured.

Category vs. catalog

TermDefinition
CatalogA Shopify store. If there's more than one store, each one is its own catalog. If there's only one store, leave catalog out. It defaults to -1.
CategoryOne listing (collection) of products within that catalog, identified by category_id.

Important

category_id and catalog are different values and easy to mix up. A catalog is the store; a category is one collection within it.

Shopify stores

Every Page in the Malachyte Portal corresponds to a Shopify Collection. Collections are synced with the rest of the product data (see Permissions & Syncs).

category_id is the numeric Shopify collection ID (for example 123456789), not the collection handle (for example mens-boots). Malachyte's search reads each product's collection IDs from Shopify.

To find a collection's numeric ID:

  1. In the Shopify Admin, go to Products → Collections.
  2. Open the collection.
  3. Copy the number at the end of the browser URL, for example admin.shopify.com/store/your-store/collections/123456789.

Headless and non-Shopify stores

Headless stores don't have Shopify collections. Instead, the client defines categories in a field in their product export (catalog file). The recommended format is category_id:category_name, for example 101:Men's Boots. A product can belong to more than one category.

The client chooses the category_id, which must be a whole number (an integer), for example 101. It's the value you pass in POST /v1/listing/{category_id}, so use the same ID in the catalog file and in the request.

Using category_id in a request

Pass the category ID in the path. See the PLP API reference for all request fields.

POST /v1/listing/123456789

{
"search_component_id": "7b6c5432-e89b-12d3-a456-426614174000",
"visitor_id": "3e92322a-d473-4c81-ab80-82dba7c31e65",
"k": 24
}

Missing or empty categories

SituationResponse
Category doesn't exist, has no products, or all products are filtered out404 Not Found

Onboarding checklist

  • Confirm whether the client is on Shopify or headless.
  • List the categories (collections) the client wants powered by Malachyte.
  • Record the category_id for each one.
  • Confirm each category appears as a Page in the Malachyte Portal.
  • Preview each Page in the Playground.