Categories give products and bundles reusable identities for grouping and targeting. Each category has a server-generated category_id, a stable handle, and a renameable display name.
Create a category explicitly with POST /v1/categories, or let a product or bundle write create one from a display name. Flint normalizes an implicit name into a lowercase, hyphenated handle. Values that normalize to the same handle resolve to the same category. If a name cannot produce a handle, supply a valid handle when you create the category.
Use category_handles when a promotion, return reason, or return policy targets categories. The category must already exist and be active. An unknown or archived handle returns UNKNOWN_CATEGORY_HANDLE. Product and bundle writes accept handles or display names through categories, with handles taking precedence when a value also matches another category's name. Send no more than 100 categories in one write.
GET /v1/categories returns active categories by default, ordered by handle. Pass status=archived to list archived categories. The assignment counts show how many products and bundles carry a category. The targeting reference count shows whether a promotion or return configuration still points at it.
Renaming a category changes only its display name. Its handle stays fixed so existing integrations and targeting rules keep working. Archive removes a category from active pickers but preserves product and bundle membership. Flint blocks archive while live targeting references exist.
Delete is available only when assignment and targeting counts are all zero. Use it to remove a category created by mistake. Both archive and delete return the category resource.
Category names and handles can contain at most 100 characters and cannot contain >. Flint reserves that character for future category paths.