Organize with collections

A collection is a named group of products — “Peptides”, “Summer stack” — that shoppers browse and that faceted search can filter on. This guide creates a collection, assigns products to it, and reads it back through the public discovery API.

Prerequisites

• Products already created and active — see Add products.
• For the public reads, a storefront token (an opaque secret, no fixed prefix, provisioned by the platform operator; platform-wide today) or nothing at all (the catalog reads are public).

How collections surface in discovery

A collection has no status column of its own. What a shopper can see is governed by two gates that already protect the catalog:

• The store must be live.
• Only active products in the collection are hydrated into the public response.

So a collection with three products, one still in draft, publicly shows two. Collections also appear as facets in catalog search, letting shoppers narrow results by collection.

Create and populate a collection

A collection needs a slug (its stable public identity) and a title, with an optional description. Creating a collection and adding or removing its products are operator/console-managed; from the storefront you read collections back through the public API below.

Read collections publicly

Once the store is live, collections are readable with no auth (or through the storefront SDK client, which pins the tenant for you).

# list collections
curl https://api.ruo.pro/v1/tenants/nova-peptide/catalog/collections
 
# one collection and its active products
curl https://api.ruo.pro/v1/tenants/nova-peptide/catalog/collections/peptides

import { createStorefrontClient } from "@dscodotco/sdk";
 
const store = createStorefrontClient({
  apiUrl: "https://api.ruo.pro",
  tenant: "nova-peptide",
  storefrontToken: process.env.FLIGHTDECK_STOREFRONT_TOKEN!,
});
 
const { collections } = await store.collections.list();
const collection = await store.collections.get("peptides");
// collection.products — each active product, with variants

The list route returns each collection’s slug, title, and description. The detail route returns the collection plus its active products (each with variants). An unknown slug is a 404 — the SDK throws FlightdeckError with status: 404 rather than returning an empty result.

Related

• Discovery — the collection and faceted-search model in full.
• Search and discovery — filtering the catalog by collection.
• Add products — the products you assign into collections.