> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Nymble Commerce Categories API — Product Tree & Navigation
> REST API reference for Nymble Commerce category endpoints — list root categories, retrieve subcategories, and build navigation trees for your B2B storefront.
Categories organize your product catalog into a hierarchy. Use category IDs in product assignments and storefront navigation. Nymble Commerce returns categories as a tree — each root category can contain subcategories, which can themselves be nested further. All endpoints require a valid Bearer token; the `OrganizationId` is read from your JWT claims.
***
## List categories
Retrieve all categories for your organization. The response includes the full subcategory tree, so a single call gives you everything you need to render a navigation menu.
```http theme={null}
GET https://api.achievemomentum.com/api/categories
```
### Response
Array of root [category objects](#the-category-object). Each root category contains a nested `subCategories` array.
### Example
```bash theme={null}
curl -X GET "https://api.achievemomentum.com/api/categories" \
-H "Authorization: Bearer {token}"
```
```json theme={null}
{
"categories": [
{
"id": "cat_001",
"name": "Widgets",
"breadcrumb": "Widgets",
"parentId": null,
"active": true,
"imageUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/org_4e9b7f22widgets/medium",
"subCategories": [
{
"id": "cat_002",
"name": "Industrial Widgets",
"breadcrumb": "Widgets Industrial Widgets",
"parentId": "cat_001",
"active": true,
"imageUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/org_4e9b7f22widgets-industrial-widgets/medium",
"subCategories": []
},
{
"id": "cat_003",
"name": "Consumer Widgets",
"breadcrumb": "Widgets Consumer Widgets",
"parentId": "cat_001",
"active": true,
"imageUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/org_4e9b7f22widgets-consumer-widgets/medium",
"subCategories": []
}
]
},
{
"id": "cat_010",
"name": "Fasteners",
"breadcrumb": "Fasteners",
"parentId": null,
"active": true,
"imageUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/org_4e9b7f22fasteners/medium",
"subCategories": [
{
"id": "cat_011",
"name": "Bolts",
"breadcrumb": "Fasteners Bolts",
"parentId": "cat_010",
"active": true,
"imageUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/org_4e9b7f22fasteners-bolts/medium",
"subCategories": []
}
]
}
]
}
```
***
## List subcategories
Retrieve only the direct children of a specific parent category by passing the parent category's name in the path.
```http theme={null}
GET https://api.achievemomentum.com/api/categories/{category}
```
### Path parameters
The name of the parent category whose subcategories you want to retrieve, e.g. `Widgets`. Matching is case-insensitive.
### Response
Returns an array of [category objects](#the-category-object) that are direct children of the specified parent.
### Example
```bash theme={null}
curl -X GET "https://api.achievemomentum.com/api/categories/Widgets" \
-H "Authorization: Bearer {token}"
```
```json theme={null}
[
{
"id": "cat_002",
"name": "Industrial Widgets",
"breadcrumb": "Widgets Industrial Widgets",
"parentId": "cat_001",
"active": true,
"imageUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/org_4e9b7f22widgets-industrial-widgets/medium",
"subCategories": []
},
{
"id": "cat_003",
"name": "Consumer Widgets",
"breadcrumb": "Widgets Consumer Widgets",
"parentId": "cat_001",
"active": true,
"imageUrl": "https://images.nymblecommerce.com/cdn-cgi/imagedelivery/pH9SuiVIe-mPijB57aX3RQ/org_4e9b7f22widgets-consumer-widgets/medium",
"subCategories": []
}
]
```
***
## Building a navigation tree
The `GET /api/categories` response already returns the full nested tree, so for most storefront use cases you do not need to make multiple requests. Use the `subCategories` array to render each level of your menu recursively.
If you are building your own flat data structure (for example, for a faceted search sidebar), use the `parentId` field to reconstruct the hierarchy:
* Categories with `parentId: null` are root (top-level) categories.
* Categories with a non-null `parentId` are children of that parent.
* The `breadcrumb` field gives you a pre-built slash-delimited path string suitable for display or URL construction.
```json theme={null}
// Root category
{ "id": "cat_001", "name": "Widgets", "parentId": null }
// Child of cat_001
{ "id": "cat_002", "name": "Industrial Widgets", "parentId": "cat_001" }
// Child of cat_002
{ "id": "cat_005", "name": "Heavy-Duty Bolts", "parentId": "cat_002" }
```
To assign a product to a category, pass the category `name` in the `category` field when [creating or updating a product](/api-reference/products).
Category images are served through Cloudflare CDN. The `imageUrl` is constructed automatically from your `OrganizationId` and the category `breadcrumb`. You can upload a custom category image using the [Images API](/api-reference/images).
***
## The category object
Nymble Commerce's unique identifier for the category.
The organization this category belongs to.
Display name of the category.
Space-separated path from the root category to this one, e.g. `"Widgets Industrial Widgets"`. Useful for constructing URL slugs and breadcrumb navigation.
The `id` of this category's parent. `null` for root categories.
Whether the category is active and visible in the storefront.
CDN URL for the category's image at medium resolution. Substitute `/medium` with `/small` or `/large` for other sizes.
Nested array of child category objects. Follows the same shape recursively.