Search products across merchants
global_searchRead-onlyIdempotent
Use this when a user wants to find or compare product candidates across participating WooCommerce merchants. Search cards include bounded variants_compact and variant_option_values from the merchant snapshot. Option values are independent and do not prove a purchasable combination. Verify the selected variant, price and stock through its merchant Bridge handoff before confirming an offer. For a request with multiple distinct items, search each item independently (calls may run in parallel), then pass the selected p2209_id values together to verify_basket. Each offer states checkout_quote_available: only those merchants can return a WooCommerce-calculated delivered total (verify_basket quote:true). Use get_product only when a search card lacks needed indexed details.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free-text product query. Each term must match as a whole word in the native merchant catalog text (name, short description, description) or in the canonical category path, so English category terms reach catalogs written in other languages: q="mattress" returns products under home.bedroom.mattress even when their text is Italian. There is no server-side translation of product text; for language-neutral retrieval by category use leaf and the canonical filters. | |
| leaf | No | Canonical category node. Accepts a terminal leaf (e.g. beverages.alcohol.sparkling_prosecco) or any parent node (e.g. jewellery, home.bedroom): a parent matches the node and its whole subtree, so you can widen or narrow the search by moving up or down the tree. Use list_categories to browse the tree. | |
| brand | No | Brand facet filter (normalized, e.g. "nike") | |
| color | No | Bridge color family (e.g. "blue"). Common aliases are resolved to a family available in the active index. A family match does not guarantee an exact shade; read filter_semantics.color and verify the chosen product via handoff.bridge_product_url. | |
| limit | No | Max offers per page (1-25, default 10). Use next_cursor for the next page. | |
| cursor | No | Opaque next_cursor from a previous global_search with the SAME arguments; returns the next page. A cursor from a different query is rejected. | |
| gender | No | Canonical gender facet. Filtering is discovery-tolerant: untagged and unisex products can remain candidates, so verify the chosen product. Allowed values: female, male, unisex. | |
| variant | No | Constraints that must ALL hold on the SAME variant. Keys and values are the merchant's own, in any language or script (read variant_vocabulary first): {"pa_taglia":"L"}, {"size":["L","Large"]}, {"*":["rouge","rosso"]} (* = any option), or [{"keys":["pa_taglia","size"],"values":["L","Large"]}] across merchants. KaliCart never translates: pass every value you accept. match.kind: exact (ignoring case, Latin accents, separators) or normalized (same number+unit symbol, NxN, size code). Indexed snapshot: verify on the merchant before quoting. | |
| in_stock | No | true filters product-level stock in the indexed snapshot. Does not verify a selected variant or a booking slot. | |
| merchant | No | Restrict to one merchant: merchant_id as returned in result_facets.merchants or offers (e.g. "duinshop-it") or its domain. | |
| max_price | No | Upper bound in major currency units (for example 1550 means EUR 1,550 for EUR offers). A matching range may include variants above this bound; verify the chosen variant. Per-offer currency, no FX conversion. | |
| min_price | No | Lower bound in major currency units (for example 50 means EUR 50 for EUR offers). Matches overlapping variant price ranges in each offer currency; no FX conversion. Verify the chosen variant. | |
| result_facets | No | true adds result_facets: counts over ALL matching offers (not just this page) by merchant, category leaf, brand, availability, and price quartiles per currency. Use them to narrow the next call. | |
| variant_limit | No | Max matching variants returned per offer (1-500, default 50); matching_variant_count is always the full count | |
| price_currency | No | ISO 4217 currency of min_price/max_price (e.g. EUR). With it, only offers priced in that currency are returned; without it the bounds compare numbers in each offer's own currency. Needs min_price or max_price. | |
| variant_facets | No | true adds variant_vocabulary: real option keys and values with variant and in-stock counts, for the offers returned or, with no q, for the merchant (or all merchants). Use it to choose the values to pass in variant. | |
| variant_in_stock | No | true keeps only variants whose own availability is in_stock | |
| variant_price_max | No | Upper bound on the variant price (major units) | |
| variant_price_min | No | Lower bound on the variant price (major units) | |
| variant_facets_limit | No | Max values per option key in variant_vocabulary (1-200, default 40); values_total is always the full count | |
| variant_price_currency | No | ISO 4217 currency of variant_price_min/max (e.g. EUR). With it, only variants priced in that currency satisfy the bound; no FX conversion. Without it, bounds compare numbers in each variant's own currency. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| scope | No | ||
| offers | No | ||
| coverage | No | ||
| federated | No | ||
| result_count | No | ||
| guidance_code | No | ||
| applied_filters | No |