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).

⚠️

Collection management (create, assign, remove) is an operator surface today: those routes live under /v1/tenants/{tenant}/collections and take the operator token (x-operator-token), not a merchant fdk_ key. There is no self-serve merchant write route for collections yet. If you run your own store self-serve, ask the platform operator to create collections for you, or drive them through the console. The read side is fully public and is what your storefront consumes.

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

Create the collection

A collection needs a slug (its stable public identity) and a title; description is optional. This is an operator route.

curl -X POST https://api.ruo.pro/v1/tenants/nova-peptide/collections \
  -H "x-operator-token: <operator token>" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "peptides", "title": "Peptides", "description": "Our research peptides." }'

A 201 returns { "collection": { ... } } with the generated id. A duplicate slug on the tenant is a 409.

Assign a product

Add a product to the collection by its product id.

curl -X POST https://api.ruo.pro/v1/tenants/nova-peptide/collections/{collectionId}/products \
  -H "x-operator-token: <operator token>" \
  -H "Content-Type: application/json" \
  -d '{ "product_id": "prod_123" }'

A 201 means the product was newly added; a 200 means it was already a member (the end state holds either way). The response is { "added": <boolean> }.

Remove a product

curl -X DELETE https://api.ruo.pro/v1/tenants/nova-peptide/collections/{collectionId}/products/{productId} \
  -H "x-operator-token: <operator token>"

A 200 returns { "removed": true }. A membership that was never there is a 404 — not a silent success.

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

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.

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.

Variants & options Product images