Collections

A Collection groups Products for merchandising and navigation - think “Summer 2026”, “Best sellers” or a storefront department. Collections are hierarchical: each one can have a parent and a set of child collections (childrens), so you can model a tree of departments and sub-departments.

Each collection has a translatable name and a status (so you can stage a collection as draft before publishing it). A product can belong to several collections.

The Collection object

Property	Type	Required	Description
childrens	array	-	A list of direct child Collection IRIs nested under this collection. Serialized as IRI strings by default; pass ?expand=children to embed direct children (one level only). Requires the collections:read scope. Returned empty when the scope is missing.
createdAt	string	-	The date and time when the resource was created (ISO 8601 format).
id	string	-	The resource's unique identifier (UUID).
name	string | null	-	This property supports translations. The display name of the collection.
parent	string | Collection | null	-	The parent Collection to which this collection belongs, if any. Serialized as IRI string by default; pass ?expand=parent to embed the direct parent (one level only). Filter with ?exists[parent]=false to list root collections (no parent) or ?exists[parent]=true for nested ones. Requires the collections:read scope. Returned null when the scope is missing.
products	string[]	-	A list of Product IRIs the collection groups together. Requires the products:read scope. Returned empty when the scope is missing.
status	"/api/statuses/DRAFT" | "/api/statuses/ACTIVE" | "/api/statuses/ARCHIVED"	-	The status of the collection.
updatedAt	string	-	The date and time when the resource was last modified (ISO 8601 format).

Common workflows

• Build a storefront menu. Create top-level collections, then nest others under them via parent to form the navigation tree. Read it back with GET /api/collections.
• Curate a campaign. Create a draft collection, attach products to it, and flip it to active with PATCH when the campaign goes live.
• Reorganize without breaking links. Move a collection under a different parent with a PATCH; its id stays stable.

Conventions

Authentication and headers

All requests require an OAuth 2.0 bearer token:

Authorization: Bearer <token>

For the translatable name, set the active locale:

Flowkiwi-Locale: fr-FR

Partial updates

PATCH uses JSON Merge Patch with Content-Type: application/merge-patch+json.