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.
Field Name | Field Type | Required |
---|---|---|
name | string | Yes |
description | string | Yes |
image | string | No |
meta_title | string | Yes |
meta_description | string | Yes |
meta_keywords | string | No |
url_key | string | Yes |
status | integer or string (0, 1, '0', '1') | Yes |
include_in_nav | integer or string (0, 1, '0', '1') | No |
parent_id | string or integer | No |
position | string or integer | No |
- cURL
- JavaScript
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/categories
fetch('https://<your domain>/api/categories', {
headers: {
'Accept': 'application/json',
'Cookie': 'asid=<your admin cookie>'
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
{
"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.
Field Name | Field Type | Required |
---|---|---|
name | string | No |
description | string | No |
image | string | No |
meta_title | string | No |
meta_description | string | No |
meta_keywords | string | No |
url_key | string | No |
status | integer or string (0, 1, '0', '1') | No |
include_in_nav | integer or string (0, 1, '0', '1') | No |
parent_id | string or integer | No |
position | string or integer | No |
- cURL
- JavaScript
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/categories/433ba97f-8be7-4be9-be3f-a9f341f2b89f
fetch('https://<your domain>/api/categories/433ba97f-8be7-4be9-be3f-a9f341f2b89f', {
headers: {
'Accept': 'application/json',
'Cookie': 'asid=<your admin cookie>'
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
{
"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.
- cURL
- JavaScript
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/categories/433ba97f-8be7-4be9-be3f-a9f341f2b89f
fetch('https://<your domain>/api/categories/433ba97f-8be7-4be9-be3f-a9f341f2b89f', {
headers: {
'Accept': 'application/json',
'Cookie': 'asid=<your admin cookie>'
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
{
"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.
- cURL
- JavaScript
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/categories/433ba97f-8be7-4be9-be3f-a9f341f2b89f
fetch('https://<your domain>/api/categories/433ba97f-8be7-4be9-be3f-a9f341f2b89f', {
headers: {
'Accept': 'application/json',
'Cookie': 'asid=<your admin cookie>'
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
{
"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.
- cURL
- JavaScript
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/categories
fetch('https://<your domain>/api/categories', {
headers: {
'Accept': 'application/json',
'Cookie': 'asid=<your admin cookie>'
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
{
"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 Code | Description |
---|---|
400 | Bad Request - Invalid parameters |
401 | Unauthorized - Authentication required |
403 | Forbidden - Insufficient permissions |
404 | Not Found - Category doesn't exist |
500 | Server Error - Something went wrong |
Error responses follow this format:
{
"error": {
"status": 404,
"message": "Category not found"
}
}
Best Practices
- Hierarchical Structure: Create a logical category hierarchy that helps customers find products easily
- SEO Optimization: Use descriptive, keyword-rich values for meta titles, descriptions, and URL keys
- URL Keys: Create unique, short, and descriptive URL keys for better SEO and user experience
- Navigation: Use the include_in_nav field strategically to keep navigation menus clean and focused
- Category Images: Use high-quality, consistent images for categories to enhance visual appeal