Skip to main content
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. 
GET https://api.achievemomentum.com/api/categories

​
Response

​
categories
array
Array of root category objects. Each root category contains a nested subCategories array.

​
Example

curl -X GET "https://api.achievemomentum.com/api/categories" \
  -H "Authorization: Bearer {token}"

{
  "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. 
GET https://api.achievemomentum.com/api/categories/{category}

​
Path parameters

​
category
string
required
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 that are direct children of the specified parent.

​
Example

curl -X GET "https://api.achievemomentum.com/api/categories/Widgets" \
  -H "Authorization: Bearer {token}"

[
  {
    "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.
// 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.
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.

​
The category object

​
id
string
Nymble Commerce’s unique identifier for the category.
​
organizationId
string
The organization this category belongs to.
​
name
string
Display name of the category.
​
breadcrumb
string
Space-separated path from the root category to this one, e.g. "Widgets Industrial Widgets". Useful for constructing URL slugs and breadcrumb navigation.
​
parentId
string | null
The id of this category’s parent. null for root categories.
​
active
boolean
Whether the category is active and visible in the storefront.
​
imageUrl
string
CDN URL for the category’s image at medium resolution. Substitute /medium with /small or /large for other sizes.
​
subCategories
array
Nested array of child category objects. Follows the same shape recursively.