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
id	string	-	The resource's unique identifier (UUID).
status	string	-	The status of the collection.
name	string | null	-	This property supports translations. The display name of the collection.
parent	string | 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).
products	string[]	-	A list of Product IRIs the collection groups together.
childrens	string[]	-	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).
createdAt	string	-	The date and time when the resource was created (ISO 8601 format).
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 /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 and the organization scope header:

Authorization: Bearer <token>
X-Flowkiwi-Organization-Id: <organization-id>

For the translatable name, set the active locale (and optionally a fallback):

X-Flowkiwi-Locale: fr-FR
X-Flowkiwi-Locale-Fallback: en-US

Partial updates

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