Defining Categories

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

Term	Definition
Catalog	A Shopify store. A client with multiple stores can have multiple catalogs. Otherwise, `catalog` set to `-1` by default
Category	One 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:

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

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

Situation	Response
Category doesn't exist, has no products, or all products are filtered out	`404 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.