# 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"}}}}}}
```