Facet rules tools

list_site_search_facets: List the site-search facet rules for an account.
list_facets_global: List the global facet rules that apply across site search and category pages.
list_category_facets: List the category facet rules for an account.
list_facet_attributes: List the product attributes available for facet configuration.
get_facet_rule: Get the full configuration of a single facet rule.

list_site_search_facets

Lists the site-search facet rules for an account. Facets are the filter options shown alongside search results, such as Brand, Color, Price range, or Size. A facet rule controls which facets appear, their order, and how they behave, for example multi-select versus single-select. This tool returns every site-search facet rule in one response, without pagination.

Use get_facet_rule for a rule's full configuration. For global facets that apply across both site search and category pages, use list_facets_global. For category-specific facets, use list_category_facets.

Request parameters

Name	Type	Required?	Description
`merchant_key`	`str`	Yes	The merchant key identifying the account, for example `your-account`.

Response parameters

The tool returns a CustomizationsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CustomizationSummary]`	The facet rule summaries.
`error`	`str \| null`	Error message if the request failed.

The CustomizationSummary object has the following fields:

Field	Type	Description
`id`	`int`	The unique customization ID.
`name`	`str \| null`	The rule's display name.
`ruleType`	`str`	The rule type, `facet`.
`isEnabled`	`bool \| null`	Whether the rule is currently enabled.
`syncStatus`	`str \| null`	Sync status: `SUCCESS`, `QUEUED`, `FAILED`, `EXPIRED`, or `FUTURE`.
`queries`	`list[CustomizationQuery]`	The queries this facet rule applies to.
`groupBy`	`str \| null`	The group-by attribute, for example `color`.

The CustomizationQuery object has the following fields:

Field	Type	Description
`id`	`int \| null`	The query identifier.
`query`	`str \| null`	The query text, for example `green shoes`.
`type`	`str \| null`	The query type, for example `sitesearch` or `category`.

list_facets_global

Lists the global facet rules for an account. Global facet rules apply across both site-search and category pages, so shoppers see a consistent set of filter options however they navigate the catalog. This tool returns every global facet rule in one response, without pagination.

Use get_facet_rule for a rule's full configuration. For site-search facets, use list_site_search_facets. For category facets, use list_category_facets.

Request parameters

Name	Type	Required?	Description
`merchant_key`	`str`	Yes	The merchant key identifying the account, for example `your-account`.

Response parameters

The tool returns a CustomizationsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CustomizationSummary]`	The global facet rule summaries.
`error`	`str \| null`	Error message if the request failed.

The CustomizationSummary object has the following fields:

Field	Type	Description
`id`	`int`	The unique customization ID.
`name`	`str \| null`	The rule's display name.
`ruleType`	`str`	The rule type, `facet`.
`isEnabled`	`bool \| null`	Whether the rule is currently enabled.
`syncStatus`	`str \| null`	Sync status: `SUCCESS`, `QUEUED`, `FAILED`, `EXPIRED`, or `FUTURE`.
`queries`	`list[CustomizationQuery]`	The queries this facet rule applies to.
`groupBy`	`str \| null`	The group-by attribute, for example `color`.

The CustomizationQuery object has the following fields:

Field	Type	Description
`id`	`int \| null`	The query identifier.
`query`	`str \| null`	The query text, for example `green shoes`.
`type`	`str \| null`	The query type, for example `sitesearch` or `category`.

list_category_facets

Lists the category facet rules for an account. Category facet rules control which facets appear on category pages and how they behave. Unlike global facets that apply everywhere, category facets are specific to browsing. For example, a Size facet can appear only on clothing categories, or a Resolution facet only on electronics. This tool returns every category facet rule in one response, without pagination.

Use get_facet_rule for a rule's full configuration. For site-search facets, use list_site_search_facets. For global facets, use list_facets_global.

Request parameters

Name	Type	Required?	Description
`merchant_key`	`str`	Yes	The merchant key identifying the account, for example `your-account`.

Response parameters

The tool returns a CustomizationsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CustomizationSummary]`	The category facet rule summaries.
`error`	`str \| null`	Error message if the request failed.

The CustomizationSummary object has the following fields:

Field	Type	Description
`id`	`int`	The unique customization ID.
`name`	`str \| null`	The rule's display name.
`ruleType`	`str`	The rule type, `facet`.
`isEnabled`	`bool \| null`	Whether the rule is currently enabled.
`syncStatus`	`str \| null`	Sync status: `SUCCESS`, `QUEUED`, `FAILED`, `EXPIRED`, or `FUTURE`.
`queries`	`list[CustomizationQuery]`	The queries this facet rule applies to.
`groupBy`	`str \| null`	The group-by attribute, for example `color`.

The CustomizationQuery object has the following fields:

Field	Type	Description
`id`	`int \| null`	The query identifier.
`query`	`str \| null`	The query text, for example `green shoes`.
`type`	`str \| null`	The query type, for example `sitesearch` or `category`.

list_facet_attributes

Lists the product attributes available for facet configuration. Each result gives an attribute field name, such as brand, color, or Rating, that you can use when you define which facets a rule boosts, buries, excludes, or always includes. Take the name field from each result as the attribute identifier.

By default the response returns only facetable attributes. Set only_facetable to false to see every attribute. The results are paginated, so use page and limit for large catalogs, and query to search by attribute name.

Request parameters

Name	Type	Required?	Description
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Omit for account level.
`query`	`str \| null`	No	Text search to filter attributes by name, for example `brand` or `color`.
`only_facetable`	`bool`	No	When true (default), returns only attributes usable as facet filters. Set to false to see all attributes.
`page`	`int`	No	The page number, 0-based. Defaults to `0`.
`limit`	`int`	No	Results per page. Defaults to `50`, maximum `200`.
`sort_by`	`str`	No	Sort field: `NAME` (default), `ID`, `TYPE`, or `FACETABLE`.
`sort_order`	`str`	No	Sort direction: `ASC` (default) or `DESC`.

Response parameters

The tool returns a FacetAttributesResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[FacetAttribute]`	The facet attributes.
`error`	`str \| null`	Error message if the request failed.
`total`	`int \| null`	The total number of matching attributes across all pages.
`page`	`int \| null`	The current page number, 0-based.
`total_pages`	`int \| null`	The total number of pages.

The FacetAttribute object has the following fields:

Field	Type	Description
`id`	`int \| null`	The internal attribute ID.
`name`	`str`	The attribute field name. Use this value when you configure facets in a rule.
`type`	`str \| null`	The attribute type: `STR` (text), `NUM` (numeric), or `HIERARCHY`.
`facetable`	`bool \| null`	Whether this attribute can be used as a facet filter.
`stored`	`bool \| null`	Whether the attribute value is stored in the index.
`level`	`str \| null`	`PARENT` (product level) or `CHILD` (variant level).
`multiValued`	`bool \| null`	Whether a product can have multiple values for this attribute.
`siteId`	`int \| null`	The site ID if the attribute is site-specific, or null for account-level attributes.

get_facet_rule

Fetches the full configuration of a single facet rule by ID. It works for site-search, category, and global facet rules. The response returns every facet action on the rule: boosted and buried facets, always-included facets, excluded facets, associated queries, audience targeting, and scheduling metadata. The customizationItems map holds the facet actions keyed by type: boosted_facets, buried_facets, excluded_facets, and always_included_facets.

Discover rule IDs with list_site_search_facets, list_facets_global, or list_category_facets, then call this tool to inspect a specific rule's full configuration.

Request parameters

Name	Type	Required?	Description
`rule_id`	`int`	Yes	The ID of the facet rule to fetch. Discover IDs with `list_site_search_facets`, `list_facets_global`, or `list_category_facets`.
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account. Use `list_discovery_accounts` to see available accounts.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name (string). Defaults to `-1` (account level) when omitted. Use `list_discovery_sites` to discover sites.

Response parameters

The tool returns a CustomizationDetailResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`any \| null`	The full facet rule detail as freeform JSON. Includes `id`, `ruleType` (`facet`), `enabled`, `queries`, `customizationItems` (keyed by `boosted_facets`, `buried_facets`, `excluded_facets`, and `always_included_facets`), audience targeting, `startedAt`, `endedAt`, and scheduling metadata.
`error`	`str \| null`	Error message if the request failed.