Categories
The catalog tree, returned flat with a parent id on every row.
The catalog tree, returned flat with a parent_id on every row. See Products and catalog.
List categories
/api/v1/kahunacart/categories
The whole catalog tree as a flat list, each row carrying its parent_id, position, display mode, picture, translation overrides, the number of products filed directly under it, and the number a shopper finds when they click it including everything in its subtree.
Create a category
/api/v1/kahunacart/categories
Add a category to the tree. The slug is derived from the title when omitted. Omit parent_id for a top-level category. The picture is uploaded separately and is not available through this interface.
Parameters
| Name | Type | Description |
|---|---|---|
| title required | string | |
| slug optional | string | Derived from the title when omitted |
| description optional | string | Markdown, shown at the top of the category page |
| parent_id optional | integer or null | Null or absent for a top-level category |
| position optional | integer | Place among its siblings |
| display optional | string |
What the category page lists; auto shows subcategories when it has any
One of:
auto, products, subcategories, both |
| image_alt optional | string | Alt text for the category picture |
| min_qty optional | integer or null | The smallest order for every product in this category and every category under it, unless the product sets its own or is excluded. Null, blank or 0 is no rule. |
| max_qty optional | integer or null | The largest order, inherited the same way. Where a product is in two categories that both set one, the lowest maximum wins. |
| qty_step optional | integer or null | Quantities in this category have to be a multiple of this — beer by the six, tiles by the box of ten. Where two categories disagree the largest step wins. |
| translations optional | object |
Update a category
/api/v1/kahunacart/categories/{id}
Change a category's fields. Only what is sent is written. Moving a category to a different parent goes through move_category instead, which is the only call that can refuse a move that would detach a branch.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Category id |
| title optional | string | |
| slug optional | string | |
| description optional | string | |
| parent_id optional | integer or null | |
| position optional | integer | |
| display optional | string |
One of:
auto, products, subcategories, both |
| image_alt optional | string | |
| min_qty optional | integer or null | Inherited minimum; null, blank or 0 clears it |
| max_qty optional | integer or null | Inherited maximum; null, blank or 0 clears it |
| qty_step optional | integer or null | Inherited step; null, blank or 0 clears it |
| translations optional | object |
Delete a category
/api/v1/kahunacart/categories/{id}
Delete a category and its picture. Its children are adopted by its own parent rather than deleted, so removing a department never takes the catalog underneath it away. Products filed under it keep every other category they had.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Category id |
Move a category
/api/v1/kahunacart/categories/{id}/move
Give a category a new parent, a new place among its siblings, or both. A route of its own rather than a field on update_category because it is the one operation that can corrupt the tree: a parent that sits underneath the category being moved is refused with 422 instead of detaching the whole branch.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Category id |
| parent_id optional | integer or null | The new parent; null or absent moves it to the top level |
| position optional | integer | Place among the new siblings; omit to append |
Move a category up or down
/api/v1/kahunacart/categories/{id}/reorder
Swap a category with the sibling above or below it. A category already at the end of its row answers moved false rather than an error, because asking to move the first item up is a click on a button and not a fault.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Category id |
| direction optional | string |
One of:
up, downDefault:
up |
Delete a category picture
/api/v1/kahunacart/categories/{id}/image
Remove a category's picture, the row and the bytes, and return the category. Uploading a replacement is not available through this interface.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Category id |
Upload a category picture
/api/v1/kahunacart/categories/{id}/image
Upload the banner picture for a category landing page. multipart/form-data.
Settable fields are title, slug, description, parent_id, position, display and image_alt. image_path is server-derived and cannot be set. Every row carries product_count (filed directly here) and subtree_count (what a customer finds when they click it). One picture per category, so the upload replaces rather than appends.