Skip to main content

Category API

Overview

The Category API provides endpoints for managing product categories in your EverShop store. Categories help organize your product catalog into a hierarchical structure, improving navigation and product discoverability for your customers.

Endpoints

Create a Category

Creates a new product category in the system. Categories can be organized in a hierarchical structure by specifying a parent category.

Request Schema (application/json)
Field NameField TypeRequired
namestringYes
descriptionstringYes
imagestringNo
meta_titlestringYes
meta_descriptionstringYes
meta_keywordsstringNo
url_keystringYes
statusinteger or string (0, 1, '0', '1')Yes
include_in_navinteger or string (0, 1, '0', '1')No
parent_idstring or integerNo
positionstring or integerNo
POST/api/categories
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/categories
Sample Of Response
{
"data": {
"category_id": 103,
"uuid": "9ab75946a63211edb46b60d819134f39",
"status": 1,
"parent_id": 16,
"include_in_nav": 0,
"position": 22,
"created_at": "2023-02-07 00:01:47",
"updated_at": "2023-02-07 00:01:47",
"category_description_id": 82,
"category_description_category_id": 103,
"name": "Athletic Shoes",
"short_description": null,
"description": "High-performance athletic shoes for sports and training",
"image": "/assets/catalog/categories/athletic-shoes.jpg",
"meta_title": "Athletic Shoes | Performance Footwear",
"meta_keywords": "athletic shoes, running shoes, training footwear",
"meta_description": "Shop our selection of high-performance athletic shoes for all your training needs",
"url_key": "athletic-shoes",
"links": [
{
"rel": "categoryGrid",
"href": "/admin/categories",
"action": "GET",
"types": [
"text/xml"
]
},
{
"rel": "view",
"href": "/category/athletic-shoes",
"action": "GET",
"types": [
"text/xml"
]
},
{
"rel": "edit",
"href": "/admin/categories/edit/9ab75946a63211edb46b60d819134f39",
"action": "GET",
"types": [
"text/xml"
]
}
]
}
}

Update a Category

Modifies an existing product category. You can update any of the category attributes, including its hierarchical position in the catalog.

Request Schema (application/json)
Field NameField TypeRequired
namestringNo
descriptionstringNo
imagestringNo
meta_titlestringNo
meta_descriptionstringNo
meta_keywordsstringNo
url_keystringNo
statusinteger or string (0, 1, '0', '1')No
include_in_navinteger or string (0, 1, '0', '1')No
parent_idstring or integerNo
positionstring or integerNo
PATCH/api/categories/433ba97f-8be7-4be9-be3f-a9f341f2b89f
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/categories/433ba97f-8be7-4be9-be3f-a9f341f2b89f
Sample Of Response
{
"data": {
"category_id": 103,
"uuid": "9ab75946a63211edb46b60d819134f39",
"status": 1,
"parent_id": 16,
"include_in_nav": 1,
"position": 22,
"created_at": "2023-02-07 00:01:47",
"updated_at": "2023-02-07 00:01:47",
"category_description_id": 82,
"category_description_category_id": 103,
"name": "Athletic Shoes",
"short_description": null,
"description": "High-performance athletic shoes for sports and training",
"image": "/assets/catalog/categories/athletic-shoes.jpg",
"meta_title": "Athletic Shoes | Performance Footwear",
"meta_keywords": "athletic shoes, running shoes, training footwear",
"meta_description": "Shop our selection of high-performance athletic shoes for all your training needs",
"url_key": "athletic-shoes",
"links": [
{
"rel": "categoryGrid",
"href": "/admin/categories",
"action": "GET",
"types": [
"text/xml"
]
},
{
"rel": "view",
"href": "/category/athletic-shoes",
"action": "GET",
"types": [
"text/xml"
]
},
{
"rel": "edit",
"href": "/admin/categories/edit/433ba97f-8be7-4be9-be3f-a9f341f2b89f",
"action": "GET",
"types": [
"text/xml"
]
}
]
}
}

Delete a Category

Permanently removes a product category from the system. Note that this does not automatically delete associated products.

Request Schema (application/json)
No request body required
DELETE/api/categories/433ba97f-8be7-4be9-be3f-a9f341f2b89f
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/categories/433ba97f-8be7-4be9-be3f-a9f341f2b89f
Sample Of Response
{
"data": {
"category_id": 103,
"uuid": "433ba97f-8be7-4be9-be3f-a9f341f2b89f",
"status": 0,
"parent_id": 16,
"include_in_nav": 0,
"position": 22,
"created_at": "2023-02-07 00:01:47",
"updated_at": "2023-02-07 00:01:48",
"category_description_id": null,
"category_description_category_id": null,
"name": null,
"short_description": null,
"description": null,
"image": null,
"meta_title": null,
"meta_keywords": null,
"meta_description": null,
"url_key": null
}
}

Get a Category

Retrieves detailed information about a specific product category.

Request Schema (application/json)
No request body required
GET/api/categories/433ba97f-8be7-4be9-be3f-a9f341f2b89f
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/categories/433ba97f-8be7-4be9-be3f-a9f341f2b89f
Sample Of Response
{
"data": {
"category_id": 103,
"uuid": "433ba97f-8be7-4be9-be3f-a9f341f2b89f",
"status": 1,
"parent_id": 16,
"include_in_nav": 1,
"position": 22,
"created_at": "2023-02-07 00:01:47",
"updated_at": "2023-02-07 00:01:47",
"category_description_id": 82,
"category_description_category_id": 103,
"name": "Athletic Shoes",
"short_description": null,
"description": "High-performance athletic shoes for sports and training",
"image": "/assets/catalog/categories/athletic-shoes.jpg",
"meta_title": "Athletic Shoes | Performance Footwear",
"meta_keywords": "athletic shoes, running shoes, training footwear",
"meta_description": "Shop our selection of high-performance athletic shoes for all your training needs",
"url_key": "athletic-shoes",
"path": [
{
"category_id": 16,
"name": "Shoes",
"url_key": "shoes"
},
{
"category_id": 103,
"name": "Athletic Shoes",
"url_key": "athletic-shoes"
}
]
}
}

List All Categories

Retrieves a paginated list of all product categories in the system.

Request Schema (application/json)
No request body required
GET/api/categories
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/categories
Sample Of Response
{
"data": [
{
"category_id": 16,
"uuid": "7ab75946a63211edb46b60d819134f39",
"status": 1,
"parent_id": null,
"include_in_nav": 1,
"position": 1,
"created_at": "2023-02-06 10:01:47",
"updated_at": "2023-02-06 10:01:47",
"name": "Shoes",
"description": "All types of footwear",
"image": "/assets/catalog/categories/shoes.jpg",
"url_key": "shoes",
"children": [
{
"category_id": 103,
"name": "Athletic Shoes",
"url_key": "athletic-shoes"
},
{
"category_id": 104,
"name": "Casual Shoes",
"url_key": "casual-shoes"
}
]
},
{
"category_id": 17,
"uuid": "8ab75946a63211edb46b60d819134f39",
"status": 1,
"parent_id": null,
"include_in_nav": 1,
"position": 2,
"created_at": "2023-02-06 10:02:47",
"updated_at": "2023-02-06 10:02:47",
"name": "Clothing",
"description": "Apparel for all occasions",
"image": "/assets/catalog/categories/clothing.jpg",
"url_key": "clothing"
}
],
"links": {
"first": "/api/categories?page=1",
"last": "/api/categories?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "/api/categories",
"per_page": 20,
"to": 2,
"total": 2
}
}

Error Handling

All endpoints may return the following error responses:

Status CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Authentication required
403Forbidden - Insufficient permissions
404Not Found - Category doesn't exist
500Server Error - Something went wrong

Error responses follow this format:

{
"error": {
"status": 404,
"message": "Category not found"
}
}

Best Practices

  1. Hierarchical Structure: Create a logical category hierarchy that helps customers find products easily
  2. SEO Optimization: Use descriptive, keyword-rich values for meta titles, descriptions, and URL keys
  3. URL Keys: Create unique, short, and descriptive URL keys for better SEO and user experience
  4. Navigation: Use the include_in_nav field strategically to keep navigation menus clean and focused
  5. Category Images: Use high-quality, consistent images for categories to enhance visual appeal