Categories
Create, update, paginated listing, query by ID, move in the tree and delete categories — with support for page, limit (up to 200), store_id and optional metadata via include_pagination.
Overview
Category routes cover the full lifecycle: create a new category in the tree, update metadata, list with deterministic pagination, query by ID, move within the hierarchy and delete.
limit.limit is omitted or invalid.total, last_page, has_next with include_pagination=1.Create a new category.
{
"parent_id": 2,
"name": "Especialidades",
"position": 5,
"is_active": 1,
"is_anchor": 1,
"include_in_menu": 1,
"description": "Dental specialties category",
"display_mode": "PRODUCTS",
"url_key": "especialidades"
}
Update an existing category.
{
"name": "Especialidades",
"categoria": {
"name": "New name",
"description": "New description",
"is_anchor": 1
}
}
List categories with deterministic pagination, or fetch a single category by id.
GET /api2/category
GET /api2/category?page=2
GET /api2/category?limit=50
GET /api2/category?include_pagination=1
GET /api2/category?store_id=1
GET /api2/category?id=61
Move a category in the tree.
{
"name": "Especialidades",
"parent_name": "Produtos",
"after_id": null
}
Delete a category.
{
"category_id": 546
}
Link and unlink products from categories New
Besides creating, editing, listing and moving categories, the Yep Platform REST API can add or remove specific categories of a product.
The operation is incremental: only the links explicitly given are changed, and every other category linked to the product is kept.
{
"id": "SKU-123",
"type": "sku",
"add_category_ids": [60],
"remove_category_ids": [55]
}
In this example, category 60 is added and category 55 is removed, without replacing the product's full category list.
products/write permission, does not accept store_id and allows adding and removing in the same request. Parameters, validation rules, response examples and integration notes are in Incremental product category links, in the Products documentation.What's new in GET /api2/category
The category listing endpoint has been evolved to provide deterministic pagination, page-size control, explicit multi-store context and optional pagination metadata — aligning its behavior with GET /api2/products.
1) Paginated listing New
You can now walk through all categories with predictable pagination. Without page, the route returns the first page; with page=N, it returns the requested page.
1.Example
GET /api2/category?page=2
2) Optional limit support New
The endpoint accepts limit to define how many records are returned per page. Invalid values (non-numeric, arrays, negative, zero or above the maximum) are normalized to the default, ensuring no request breaks due to unexpected input.
| Rule | Value | Behavior |
|---|---|---|
| Default | 20 | Applied when limit is omitted. |
| Maximum | 200 | Hard ceiling to protect the route under high load. |
| Invalid | — | Invalid values are normalized to 20. |
Examples
GET /api2/category?limit=50
GET /api2/category?page=1&limit=200
3) Optional store_id support New
Pass store_id to make the result explicit and deterministic in multi-store scenarios. Without it, store selection follows the environment's default rule; with it, the integration takes control.
Example
GET /api2/category?store_id=1
4) Optional pagination metadata New
Optional pagination fields can now be added to the response body. They are only returned when include_pagination=1 is sent, avoiding overhead for sync routines that do not need this metadata.
1 enables). When active, the response also contains total, last_page and has_next.include_pagination=1).limit.Example
GET /api2/category?include_pagination=1
5) Single fetch by id
Preserved and compatible: pass id to fetch a single category. When id is sent, pagination parameters are ignored.
Example
GET /api2/category?id=61
Supported usage patterns
Quick reference of the tested and approved combinations for GET /api2/category.
GET /api2/category
GET /api2/category?page=2
GET /api2/category?limit=50
GET /api2/category?include_pagination=1
GET /api2/category?store_id=1
GET /api2/category?id=61
Integration recommendations
Best practices for syncing the category tree. Following these guidelines reduces rework, prevents infinite pagination and guarantees determinism in multi-store environments.
Recommended
- Always send
pageexplicitly in pagination routines. - Use
store_idwhenever the integration needs deterministic results in a multi-store environment. - Prefer
limit=50orlimit=100for regular syncs. - Use
limit=200only when there is a real need to reduce the number of calls. - Use
include_pagination=1to drive pagination loops safely (loop based onhas_next).
Avoid
- Sending parameters as arrays in scalar fields — for example
id[]orlimit[]. - Relying on implicit ordering between pages in multi-store scenarios without
store_id. - Combining
idwithpage/limit: when fetching by ID, pagination parameters are ignored.
Sync tip
For recurring syncs of the category tree, combine store_id + limit=100 + include_pagination=1. You get determinism, balanced throughput and a reliable stop condition (has_next=false).