Categories

Categories are a hierarchical tree for grouping products. A product can sit in any number of categories. Each category has a localized name, a slug, a position among its siblings, a status, and custom fields, starting with a rich-text Description.

In the admin

Categories live under Catalog → Categories.

1. Under Add a category, type a name, choose a parent (or (top level)) and click Add. The slug is generated from the name.
2. In the Tree, drag a row’s handle to reorder; drag right or left while dragging to nest or promote. The hover arrows do the same one step at a time. The tree editor allows up to six levels.
3. Hover a row and click Edit category to open it. Under Identity, edit the Name, Slug and Status and click Save. Under Fields, edit the description and any other custom fields.
4. To assign products, open a product and use its Categories section: tick categories, then click Save.

Several products at once: select them on the products list and use Categories in the bulk bar to add, remove or replace assignments.

With the API

Method	Path	What it does
GET	/v1/categories	The whole tree, flat, ordered by position
POST	/v1/categories	Create
GET / PATCH / DELETE	/v1/categories/{id}	Read, update, delete
GET	/v1/products/{id}/categories	A product’s categories
PUT	/v1/products/{id}/categories	Replace a product’s categories

curl -X POST https://api.minipim.com/v1/categories \
  -H "Authorization: Bearer pim_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": { "en_US": "Banner Stands" }, "slug": "banner-stands", "parentId": null }'

GET /v1/categories returns every category in one call. Build the hierarchy client-side by joining on parentId (roots have parentId: null). Pass ?status=active for storefronts, and ?limit= / ?offset= (limit up to 1000) only if you need to page a very large tree.

To list products in a category, use GET /v1/products?categoryId=…. That matches direct assignments only. Add includeDescendants=true to include the whole subtree in one query. Full reference: api.minipim.com/docs.

Rules and limits

• name (a locale-to-text map) and slug are required on create. status defaults to active.
• A category’s status applies to that category only. It doesn’t cascade to children and doesn’t change its products’ status. Storefronts that hide a subtree should check ancestors while walking parentId.
• Slug uniqueness is only enforced among categories assigned to the same channel. Categories with no channel aren’t checked, so keep their slugs unique yourself.
• The API refuses to make a category its own parent or move it under one of its descendants (422).
• Deleting a category moves its children up one level and removes it from products. The products themselves are untouched.
• PUT /v1/products/{id}/categories replaces the full list in the order given. Send [] to clear.
• Custom fields are validated against the organization’s category family, the same way product attributes are. The admin can edit their values; new category fields beyond Description are added through the API: create the attribute with "entityKind": "category", then attach it to the category family (GET /v1/attribute-families?entityKind=category returns it). See Attribute families.
• Category PATCH merges attributes per code, like products.
• Writes emit category.created, category.updated and category.deleted. Assignment changes emit category.assigned / category.unassigned plus one product.updated.