Categories tools

list_categories: List the categories in the product taxonomy.
list_dynamic_categories: List the rule-based dynamic categories in an account.
get_dynamic_category: Get the full definition of a single dynamic category.

list_categories

Lists the categories in your product taxonomy, the structure that powers category-page navigation. For example, a category path might read Home > Clothing > Shoes.

The response gives you every category with its IDs, display name, full path, and domain key. Use site_group_id=-1, the default, for account-level categories, or a specific site group ID for site-level categories. For rule-based categories whose membership is set by conditions, use list_dynamic_categories.

Request parameters

Name	Type	Required?	Description
`site_group_id`	`str`	No	The site group ID. Use `-1` for account-level categories, the default, or a specific site group ID for site-level categories.

Response parameters

The tool returns a CategoriesResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CategoryItem]`	The categories in the taxonomy.
`count`	`int`	The total number of categories.
`error`	`str \| null`	Error message if the request failed.

The CategoryItem object has the following fields:

Field	Type	Description
`id`	`str \| null`	The internal category record ID.
`accountId`	`str \| null`	The account this category belongs to.
`siteId`	`int \| null`	The site this category belongs to.
`categoryId`	`str \| null`	The category ID used in search queries.
`categoryPaths`	`str \| null`	The full category path, for example `Home/Clothing/Shoes`.
`displayName`	`str \| null`	The category's display name.
`domainKey`	`str \| null`	The domain key this category belongs to.
`originalCategoryId`	`str \| null`	The original category ID from the catalog feed.
`extendedCategoryPath`	`list[ExtendedCategoryPath]`	The structured category path segments.

The ExtendedCategoryPath object has the following fields:

Field	Type	Description
`id`	`str \| null`	The category path segment ID.
`name`	`str \| null`	The category path segment display name.

list_dynamic_categories

Lists the dynamic categories in an account. Dynamic categories are rule-based: their product membership comes from conditions rather than manual curation, so products move in and out as they match the rules.

The response gives you paginated summaries with each category's name, associated catalog, conditions, and sync status. Use get_dynamic_category when you need the full definition of one category. For the manually curated taxonomy, use list_categories.

Request parameters

Name	Type	Required?	Description
`account_name`	`str \| null`	No	The account name. Required if you have access to more than one account.
`site_group_id`	`str \| int \| null`	No	A site group ID or site name. Defaults to the account level (`-1`).
`page`	`int`	No	The page number, zero-based. Defaults to `0`.
`limit`	`int`	No	The number of results per page. Defaults to `10`.
`sort_by`	`str`	No	The field to sort by. Defaults to `lastModifiedAt`.
`sort_order`	`str`	No	The sort direction, `ASC` or `DESC`. Defaults to `DESC`.
`query`	`str \| null`	No	A search term to filter categories by name.
`catalog_name`	`str \| null`	No	A catalog name to filter by.

Response parameters

The tool returns a DynamicCategoriesResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[DynamicCategorySummary]`	The dynamic categories in the account.
`error`	`str \| null`	Error message if the request failed.

The DynamicCategorySummary object has the following fields:

Field	Type	Description
`id`	`int`	The dynamic category's unique ID.
`categoryId`	`str \| null`	The category identifier.
`categoryName`	`str \| null`	The category's display name.
`categoryNote`	`str \| null`	An optional note.
`catalogName`	`str \| null`	The associated catalog name.
`merchantId`	`int \| null`	The merchant this category belongs to.
`groupId`	`int \| null`	The group ID used to group dynamic categories.
`createdAt`	`int \| null`	Unix timestamp in milliseconds of when the category was created.
`createdBy`	`str \| null`	The user who created the category.
`lastModifiedAt`	`int \| null`	Unix timestamp in milliseconds of the last modification.
`lastModifiedBy`	`str \| null`	The user who last modified the category.
`syncedAt`	`int \| null`	Unix timestamp in milliseconds of the last sync.
`toBeDeleted`	`bool \| null`	Whether the category is marked for deletion.
`productIds`	`list[str]`	The product IDs included in this category.
`conditionConfig`	`any \| null`	The condition rules, as a query and filter configuration.
`paths`	`list[list[CategoryPathNode]] \| null`	The category hierarchy paths.

get_dynamic_category

Returns the full definition of a single dynamic category, including its condition rules, product IDs, hierarchy paths, catalog association, and sync status. Use list_dynamic_categories first to find the category ID you want.

Request parameters

Name	Type	Required?	Description
`category_id`	`int`	Yes	The category ID returned by `list_dynamic_categories`.
`account_name`	`str \| null`	No	The account name. Required if you have access to more than one account.
`site_group_id`	`str \| int \| null`	No	A site group ID or site name. Defaults to the account level (`-1`).

Response parameters

The tool returns a DynamicCategoryResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`DynamicCategorySummary \| null`	The full dynamic category record.
`error`	`str \| null`	Error message if the request failed.

The DynamicCategorySummary object has the fields documented under list_dynamic_categories.

Each entry in the paths field is a list of CategoryPathNode objects, which have the following fields:

Field	Type	Description
`id`	`str \| null`	The category path node ID.
`name`	`str \| null`	The category path node display name.