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 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

POST/api/categories

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
  });

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 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

PATCH/api/categories/433ba97f-8be7-4be9-be3f-a9f341f2b89f

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
  });

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
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
  });

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
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
  });

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
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
  });

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 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

Overview​

Endpoints​

Create a Category​

Update a Category​

Delete a Category​

Get a Category​

List All Categories​

Error Handling​

Best Practices​

Overview

Endpoints

Create a Category

Update a Category

Delete a Category

Get a Category

List All Categories

Error Handling

Best Practices