# Category

Category information and navigation

## Retrieve category detail page

> Returns category information along with subcategory hierarchy for navigation.\
> \
> \*\*Response Behavior:\*\*\
> \
> \*\*1. Landing Page Mode\*\* (shallow categories)\
> When the category depth is at or below the configured maximum \*(Source: Dynamic/Real-time Configuration)\*:\
> \* Returns category information with subcategories\
> \* Includes up to 2 levels of nested subcategories\
> \* Suitable for category landing pages\
> \
> \*\*2. Listing Mode\*\* (deep categories)\
> When the category depth exceeds the maximum:\
> \* Returns product listing (faceted search results)\
> \* Includes category metadata alongside product results\
> \* Uses category-specific sort options when configured\
> \
> \*\*Subcategory Structure:\*\*\
> \* First level: Direct children of the requested category\
> \* Second level: Children of direct children\
> \* Each subcategory includes navigation URLs

```json
{"openapi":"3.1.0","info":{"title":"Product API - Product Catalog & Detail Information","version":"1.0.0"},"tags":[{"name":"Category","description":"Category information and navigation"}],"servers":[{"description":"Commerce API Server","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL (e.g., your-store.akinon.com)"}}}],"paths":{"/category/{category_id}/":{"get":{"tags":["Category"],"operationId":"getCategoryDetail","summary":"Retrieve category detail page","description":"Returns category information along with subcategory hierarchy for navigation.\n\n**Response Behavior:**\n\n**1. Landing Page Mode** (shallow categories)\nWhen the category depth is at or below the configured maximum *(Source: Dynamic/Real-time Configuration)*:\n* Returns category information with subcategories\n* Includes up to 2 levels of nested subcategories\n* Suitable for category landing pages\n\n**2. Listing Mode** (deep categories)\nWhen the category depth exceeds the maximum:\n* Returns product listing (faceted search results)\n* Includes category metadata alongside product results\n* Uses category-specific sort options when configured\n\n**Subcategory Structure:**\n* First level: Direct children of the requested category\n* Second level: Children of direct children\n* Each subcategory includes navigation URLs","parameters":[{"name":"category_id","in":"path","required":true,"description":"Unique identifier of the category to retrieve.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Category detail retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryDetailResponse"}}}},"404":{"description":"Category not found.\n\nOccurs when:\n* No category exists with the specified ID\n* Category depth is 1 or less (root categories are not accessible)"}}}}},"components":{"schemas":{"CategoryDetailResponse":{"type":"object","description":"Category detail response with subcategory navigation.","required":["pk","name"],"properties":{"pk":{"type":"integer","description":"Category identifier"},"name":{"type":"string","description":"Display name of the category.\n\nMay be translated based on active language settings."},"menuitemmodel":{"type":["string","null"],"format":"uuid","description":"UUID of the associated menu item for navigation.\n\nNull if the category has no menu configuration."},"absolute_url":{"type":"string","format":"uri","description":"Canonical URL for this category.\n\nUse this for SEO-friendly category links."},"attributes":{"type":"object","description":"Category-specific attributes.\n\nMay include display settings, featured flags, etc.","additionalProperties":true},"uuid":{"type":"string","format":"uuid","description":"Universally unique identifier for the category."},"depth":{"type":"integer","description":"Hierarchical depth level of the category.\n\nRoot categories have depth 1, their children have depth 2, etc."},"path":{"type":"string","description":"Materialized path representing the category's position in the hierarchy.\n\nUsed internally for efficient hierarchical queries."},"sort_option":{"type":["integer","null"],"description":"ID of the default sort option for product listings in this category.\n\nWhen set, product listings automatically use this sort order."},"sub_categories":{"type":"array","description":"Nested subcategories up to 2 levels deep.\n\nFirst level contains direct children, second level contains their children.","items":{"$ref":"#/components/schemas/CategoryNodeNested"}}}},"CategoryNodeNested":{"type":"object","description":"Category node with nested children.","allOf":[{"$ref":"#/components/schemas/CategoryNode"},{"type":"object","properties":{"children":{"type":"array","description":"Child categories (one level deep).","items":{"$ref":"#/components/schemas/CategoryNode"}}}}]},"CategoryNode":{"type":"object","description":"Basic category node information.","required":["pk","name"],"properties":{"pk":{"type":"integer","description":"Category identifier"},"name":{"type":"string","description":"Display name of the category"},"menuitemmodel":{"type":["string","null"],"format":"uuid","description":"UUID of associated menu item"},"absolute_url":{"type":"string","format":"uri","description":"Canonical URL for this category"},"attributes":{"type":"object","additionalProperties":true},"uuid":{"type":"string","format":"uuid"},"depth":{"type":"integer","description":"Hierarchical depth level"},"path":{"type":"string","description":"Materialized path"}}}}}}
```

## Retrieve categories for a product

> Returns all category nodes associated with a specific product.\
> \
> \*\*Response Order:\*\*\
> Categories are returned ordered by their path, ensuring hierarchical consistency for breadcrumb display.

```json
{"openapi":"3.1.0","info":{"title":"Product API - Product Catalog & Detail Information","version":"1.0.0"},"tags":[{"name":"Category","description":"Category information and navigation"}],"servers":[{"description":"Commerce API Server","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL (e.g., your-store.akinon.com)"}}}],"paths":{"/products/{product_id}/category_nodes/":{"get":{"tags":["Category"],"operationId":"getProductCategoryNodes","summary":"Retrieve categories for a product","description":"Returns all category nodes associated with a specific product.\n\n**Response Order:**\nCategories are returned ordered by their path, ensuring hierarchical consistency for breadcrumb display.","parameters":[{"name":"product_id","in":"path","required":true,"description":"Unique identifier of the product.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Product categories retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CategoryNode"}}}}}}}}},"components":{"schemas":{"CategoryNode":{"type":"object","description":"Basic category node information.","required":["pk","name"],"properties":{"pk":{"type":"integer","description":"Category identifier"},"name":{"type":"string","description":"Display name of the category"},"menuitemmodel":{"type":["string","null"],"format":"uuid","description":"UUID of associated menu item"},"absolute_url":{"type":"string","format":"uri","description":"Canonical URL for this category"},"attributes":{"type":"object","additionalProperties":true},"uuid":{"type":"string","format":"uuid"},"depth":{"type":"integer","description":"Hierarchical depth level"},"path":{"type":"string","description":"Materialized path"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.akinon.com/commerce-openapis/products/category.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.