# Collections

> A Collection groups products into a hierarchy for merchandising and navigation.

A **Collection** groups [Products](/api/product-management/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

## 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`](/api/product-management/collections/list/).
- **Curate a campaign.** Create a `draft` collection, attach products to it, and flip it to `active` with [`PATCH`](/api/product-management/collections/update/) 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](https://datatracker.ietf.org/doc/html/rfc7396) with `Content-Type: application/merge-patch+json`.