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.
View input schema
{
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "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": {
"type": "string",
"description": "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": {
"type": "string",
"description": "Brand facet filter (normalized, e.g. \"nike\")"
},
"gender": {
"type": "string",
"enum": [
"female",
"male",
"unisex"
],
"description": "Canonical gender facet. Filtering is discovery-tolerant: untagged and unisex products can remain candidates, so verify the chosen product. Allowed values: female, male, unisex."
},
"color": {
"type": "string",
"description": "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."
},
"in_stock": {
"type": "boolean",
"description": "true filters product-level stock in the indexed snapshot. Does not verify a selected variant or a booking slot."
},
"min_price": {
"type": "number",
"minimum": 0,
"description": "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."
},
"max_price": {
"type": "number",
"minimum": 0,
"description": "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."
},
"price_currency": {
"type": "string",
"pattern": "^[A-Za-z]{3}$",
"description": "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."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 25,
"description": "Max offers per page (1-25, default 10). Use next_cursor for the next page."
},
"variant": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
},
"maxItems": 32
}
]
}
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"keys": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 16
},
"values": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 32
}
},
"required": [
"values"
],
"additionalProperties": false
},
"maxItems": 4
}
],
"description": "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."
},
"variant_facets": {
"type": "boolean",
"description": "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_facets_limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "Max values per option key in variant_vocabulary (1-200, default 40); values_total is always the full count"
},
"variant_in_stock": {
"type": "boolean",
"description": "true keeps only variants whose own availability is in_stock"
},
"variant_price_min": {
"type": "number",
"minimum": 0,
"description": "Lower bound on the variant price (major units)"
},
"variant_price_max": {
"type": "number",
"minimum": 0,
"description": "Upper bound on the variant price (major units)"
},
"variant_price_currency": {
"type": "string",
"pattern": "^[A-Za-z]{3}$",
"description": "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."
},
"variant_limit": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"description": "Max matching variants returned per offer (1-500, default 50); matching_variant_count is always the full count"
},
"merchant": {
"type": "string",
"maxLength": 253,
"description": "Restrict to one merchant: merchant_id as returned in result_facets.merchants or offers (e.g. \"duinshop-it\") or its domain."
},
"result_facets": {
"type": "boolean",
"description": "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."
},
"cursor": {
"type": "string",
"maxLength": 512,
"description": "Opaque next_cursor from a previous global_search with the SAME arguments; returns the next page. A cursor from a different query is rejected."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}