ItemCategories API

Overview

Core Concept

The ItemCategories object provides methods for retrieving category information from the category hierarchy. Categories are organized in a tree structure with categories at the top level and attribute groups (subcategories) beneath them.

Category vs Attribute Group: In the hierarchy, a category (categoryId) represents a top-level category like "Services" or "Materials". An attribute group (attributeGroupId) represents a subcategory within a category, such as "General Labor" under "Services".

Hierarchy Example

Home Improvement (category)
├── Flooring (category)
│   ├── Hardwood (category)
│   │   ├── Oak Varieties (attributeGroup)
│   │   └── Maple Varieties (attributeGroup)
│   └── Laminate (category)
│       └── Budget Options (attributeGroup)
└── Services (category)
    ├── General Labor (attributeGroup)
    └── Specialized Labor (attributeGroup)

ItemCategories.get(categoryId, attributeGroupId)

Method

Retrieves a category by categoryId and optional attributeGroupId. Returns the category details including name and the full path from root category to the attribute group.

Parameters

Parameter	Type	Required	Description
`categoryId`	number	Yes	The category ID to retrieve
`attributeGroupId`	number	No	The attribute group ID. If provided, must belong to the specified category.

Returns

Returns an object with category details, or null if not found.

Property	Type	Description
`categoryId`	number	The category ID
`attributeGroupId`	number\|null	The attribute group ID, or null if only categoryId was provided
`name`	string	The display name of the category or attribute group
`path`	string[]	Array of names from root category to this attribute group

Examples

// Get category only (no attributeGroupId)
var category = ItemCategories.get(100);
if (category) {
  console.log('Name: ' + category.name);
  console.log('Path: ' + category.path.join(' > '));
  // Output: "Services > Labor"
}

// Get attribute group with categoryId and attributeGroupId
var category = ItemCategories.get(100, 200);
if (category) {
  console.log('Category ID: ' + category.categoryId);
  console.log('Attribute Group ID: ' + category.attributeGroupId);
  console.log('Name: ' + category.name);
  console.log('Path: ' + category.path.join(' > '));
  // Output: "Services > Labor > General Labor"
}

// Handle not found
var category = ItemCategories.get(999999);
if (!category) {
  console.log('Category not found');
}

Returns null when:

The categoryId does not exist or is deleted
The attributeGroupId does not exist or is not visible
The attributeGroupId does not belong to the specified categoryId

ItemCategories.search(options)

Method

Searches for categories in the category hierarchy. Returns categories and attribute groups at the specified level with pagination support.

Options

Option	Type	Default	Description
`search`	string	null	Filter by name (partial match)
`parentId`	number	null	Parent category ID. If null, returns root-level categories.
`skip`	number	0	Number of results to skip (for pagination)
`maxCount`	number	25	Maximum results to return (1-200)

Returns

Returns an object with search results.

Property	Type	Description
`items`	array	Array of matching categories and attribute groups
`totalCount`	number	Total number of matching items
`skip`	number	Number of items skipped
`maxCount`	number	Maximum items requested
`parentId`	number\|null	The parent category ID used in the search

Item Properties

Each item in the results array contains:

Property	Type	Description
`type`	string	`"category"` or `"attributeGroup"`
`categoryId`	number	Category ID (for categories)
`id`	number	Attribute group ID (for attribute groups)
`name`	string	Display name
`parentCategoryId`	number\|null	Parent category ID (for categories)

Examples

// Get root-level categories
var results = ItemCategories.search({});
for (var i = 0; i < results.items.length; i++) {
  var item = results.items[i];
  console.log(item.name + ' (' + item.type + ')');
}

// Get children of a specific category
var results = ItemCategories.search({ parentId: 100 });
console.log('Found ' + results.totalCount + ' items');

// Search by name
var results = ItemCategories.search({
  search: 'Labor',
  maxCount: 10
});

// Pagination
var results = ItemCategories.search({
  parentId: 100,
  skip: 20,
  maxCount: 20
});

Practical Examples

Code Examples

Display Category Breadcrumb

// Get an item and display its category path
var item = Items.get(12345);
if (item && item.attributeGroupId) {
  var category = ItemCategories.get(item.categoryId, item.attributeGroupId);
  if (category) {
    template.categoryDisplay.value = category.path.join(' > ');
    // Output: "Home Improvement > Flooring > Hardwood > Oak Varieties"
  }
}

Build Category Tree Navigation

// Navigate through the category hierarchy
function displayLevel(parentId) {
  var results = ItemCategories.search({ parentId: parentId });

  console.log('--- Level: ' + (parentId || 'Root') + ' ---');
  for (var i = 0; i < results.items.length; i++) {
    var item = results.items[i];
    if (item.type === 'category') {
      console.log('[Category] ' + item.name + ' (ID: ' + item.categoryId + ')');
    } else {
      console.log('[Attribute Group] ' + item.name + ' (ID: ' + item.id + ')');
    }
  }
}

// Display root level
displayLevel(null);

// Display children of category 100
displayLevel(100);

Find Items in a Category

// Get category info for filtering
var category = ItemCategories.get(100, 200);
if (category) {
  console.log('Looking for items in: ' + category.name);
  console.log('Full path: ' + category.path.join(' > '));

  // Search for items in this category
  var items = Items.search(category.name);
  console.log('Found ' + items.length + ' items');
}

Use with Items API

// Get item details including category
var item = Items.get(12345);
if (item) {
  console.log('Item: ' + item.name);
  console.log('Price: $' + item.price);

  // Display category info
  if (item.categoryId) {
    console.log('Category ID: ' + item.categoryId);
    console.log('Attribute Group ID: ' + item.attributeGroupId);
    console.log('Category Path: ' + item.categoryPath.join(' > '));
  } else {
    console.log('No category assigned');
  }
}