search_products

Tool of Kifly — Agentic Commerce & Payments

Search or browse Kifly's product catalog. Multilingual semantic search (100+ languages). Returns a JSON-LD ItemList with `kifly:totalCatalogSize`. When empty, `kifly:emptyReason` is 'empty_catalog' | 'no_matches_for_query' — on 'no_matches_for_query' tell the buyer nothing matched rather than guessing, then offer `kifly:suggestions` (related products — NOT matches) and `kifly:availableCategories` (what the catalog carries) so you can help without a second search. Results carry `kifly:relevanceScore` [0–1]; a semantic similarity floor filters out irrelevant results automatically. Omit `q` to browse. In cross-seller (network) results, each item's `kifly:seller` is just the seller's handle — look it up once in the ItemList's `kifly:sellers` map (keyed by handle) to read `delivery_fee_cents` and `delivery_coverage` — `nationwide:true` for all 50 states, a `states` list, or `coverage_configured:false` meaning the seller ships NOWHERE yet (empty `states` is NOT nationwide). `delivery_coverage.cities` may be capped — compare `cities.length` against `city_count` and call `get_seller` for the full list if fewer. Seller-scoped results carry the full record once at the list level (`kifly:seller` on the ItemList itself) instead. Each item also carries `kifly:variantId`. When a product has 2+ size/style variants, `kifly:hasVariant` lists each with its own `kifly:variantId` — pass the matching one to `create_cart`/`add_to_cart` for the buyer's chosen size/color (capped at 20 variants; `kifly:variantCount` is set if the product has more — vanishingly rare today). `image` is capped to 2 URLs per product — if `kifly:imageCount` is present, there are more than shown (not retrievable via this API; the cap is a hard limit, not a paginated detail). Each result's `offers` carries `kifly:purchasable`: when **false**, the seller is discovery-only (directory-tier or not yet able to charge) — checkout will hand off / fail, so present it as a referral, not a buy. `availability:InStock` is about stock, NOT buyability — read `kifly:purchasable` to decide whether to route the buyer to checkout. **You can read the delivery fee and check coverage from here — no need to call `set_shipping_address` just to learn the cost.** **Pagination (browse only):** when `kifly:hasMore` is true, pass `kifly:nextCursor` as `cursor` to fetch the next page. **Seller filter:** pass `seller_handle` to scope results to one seller. **Category filter:** free-text, case-insensitive (e.g. 'fashion'). **Multiple queries:** pass `q` as an array (up to 5) to try several phrasings in one call instead of N separate searches. **Before checkout, call `set_shipping_address`.**