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. An unknown or deleted 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, ordered by handle. 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.
Delete permanently removes a category and returns its last snapshot with status=deleted. Delete is available only when the category has no product or bundle assignments and no promotion, return reason, or return policy references. Deleted promotions do not block deletion. Use it to remove a category created by mistake.
Category names and handles can contain at most 100 characters and cannot contain >. Flint reserves that character for future category paths.