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=61Move a category in the tree.
{
"name": "Especialidades",
"parent_name": "Produtos",
"after_id": null
}Delete a category.
{
"category_id": 546
}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=22) 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=2003) 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=14) 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=15) 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=61Supported 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).