# Categories

> A Category is a node in a hierarchical taxonomy that classifies products and carries attributes.

A **Category** classifies your products in a **hierarchy**. Each category has a translatable `name`, an optional `parent`, and its direct `childrens` - so categories form a tree (Apparel → Shoes → Running shoes). Products are assigned to categories through the category's `products` list.

Categories also carry **attributes** - the properties that products in that category can describe themselves with (a material, a season, a heel height). Attributes come in two kinds, each documented separately:

- **[Attribute strings](/api/product-management/attribute-strings/)** - free-text attributes, with [string values](/api/product-management/attribute-string-values/).
- **[Attribute lists](/api/product-management/attribute-lists/)** - attributes with a predefined set of options, as [list values](/api/product-management/attribute-list-values/).

A category's `attributes` field is the read-only union of both, also exposed on its own as [Attributes](/api/product-management/attributes/).

## The Category object

## Common workflows

- **Build the tree.** Create top-level categories, then create child categories with a `parent` pointing at them.
- **Classify products.** Add products to a category's `products` list.
- **Describe with attributes.** Attach [attribute strings](/api/product-management/attribute-strings/) or [attribute lists](/api/product-management/attribute-lists/) to a category, then set their values on the category's products.

## 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`.