Categories tools

list_categories: List the categories in the product taxonomy.
search_dynamic_categories: List the rule-based dynamic categories in an account, or fetch one by ID.

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 search_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.

search_dynamic_categories

Searches the dynamic categories in an account, or fetches one by ID. 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.

Omit category_id to list paginated summaries, each with the category's name, associated catalog, conditions, and sync status. Pass category_id to fetch a single category's complete definition, including its condition rules, product IDs, hierarchy paths, catalog association, and sync status. For the manually curated taxonomy, use list_categories.

Request parameters

Name	Type	Required?	Description
`category_id`	`int \| null`	No	The dynamic category ID. Omit to list all dynamic categories; provide to fetch one.
`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`. Ignored when `category_id` is set.
`limit`	`int`	No	The number of results per page. Defaults to `10`. Ignored when `category_id` is set.
`sort_by`	`str`	No	The field to sort by. Defaults to `lastModifiedAt`. Ignored when `category_id` is set.
`sort_order`	`str`	No	The sort direction, `ASC` or `DESC`. Defaults to `DESC`. Ignored when `category_id` is set.
`query`	`str \| null`	No	A search term to filter categories by name. Ignored when `category_id` is set.
`catalog_name`	`str \| null`	No	A catalog name to filter by. Ignored when `category_id` is set.

Response parameters

The tool returns a DynamicCategoriesResponse when category_id is omitted, or a DynamicCategoryResponse when it's provided.

The DynamicCategoriesResponse object has 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 DynamicCategoryResponse object has 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 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.

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.