Serveur MCP

WEM Price Compare

ai.wem3/wem-price-compare
Commerce et retail Public et accessible MCP 2026-07-28

Ce que fait ce MCP

Searches and compares retailer product offers, prices, ratings, shipping, price history, and verification evidence.

compare_offers
Compare retailer offers for one product
Lists the retailer offers WEM's catalogue holds for one product, current prices first and each group cheapest first, with WEM's 90-day price low (null when the product is held only in another currency). The product is found by barcode, catalogue slug or wem3.ai/pl/ URL, WEM ID, or a title (a model name, ASIN, MPN or merchant SKU) that must pass a relevance check; there is no live retailer search. A barcode, slug or WEM ID match is the product itself; a title match is inferred and marked so in `identity`. A marketplace offer priced far below the product's other offers is withheld and counted in `filtered`. When WEM does not hold the product, `found` is false and `nextTool` names search_products with a query.
Lecture seule
Schéma d’entrée
{'type': 'object', 'anyOf': [{'required': ['gtin']}, {'required': ['slug']}, {'required': ['wem_id']}, {'required': ['title']}], 'properties': {'gtin': {'type': 'string', 'description': 'Product barcode: EAN-13, UPC-A, EAN-8 or GTIN-14. The strongest identifier.'}, 'slug': {'type': 'string', 'description': 'WEM catalogue slug, or a wem3.ai/pl/{slug} URL / host path. Hosts may pass either form.'}, 'title': {'type': 'string', 'description': 'Product or model name, or an ASIN, MPN or merchant SKU (e.g. AF400UK). The weakest identifier: used only when no barcode, slug or WEM ID is given, and only if it passes a relevance check; otherwise `found` is false rather than a guess.'}, 'wem_id': {'type': 'string', 'description': 'WEM ID (W + 10 Crockford characters + check). Active catalogue products only.'}, 'currency': {'type': 'string', 'description': "ISO 4217 code for the shopper's market. Default GBP. Decides which market's offers WEM returns from its catalogue, not just how the answer reads ; WEM does not infer the market from IP. When WEM holds the product only in another currency it says so rather than presenting a foreign listing as the answer."}}}
Schéma de sortie
{'type': 'object', 'required': ['found'], 'properties': {'next': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'reason': {'type': 'string'}, 'surface': {'enum': ['chrome_extension'], 'type': 'string'}}, 'description': "Present when WEM's set of offers is thin. chrome_extension is a page that compares the same product on any retailer page, including shops without an affiliate programme."}, 'found': {'type': 'boolean', 'description': 'False when the product is not in WEM’s catalogue. The rest of the fields below are then absent ; that does not mean the product is unavailable or unpriced. `unavailable` distinguishes an outage from a miss. `nextTool`, when present, names the next lookup.'}, 'links': {'type': 'array', 'items': {'type': 'object', 'properties': {'url': {'type': 'string', 'description': 'WEM tracked redirect. The full URL; a shortened or rewritten form is a different link.'}, 'price': {'type': ['number', 'null'], 'description': 'Null for a listing in `unpriced`. The markdown says "see price at Amazon" in place of a figure.'}, 'currency': {'type': ['string', 'null']}, 'markdown': {'type': 'string', 'description': 'The same link as `[Retailer — £0.00](url)`, for hosts rendering markdown.'}, 'retailer': {'type': 'string'}}}, 'description': 'The links from `offers`, cheapest first, pre-formatted. Each opens the retailer’s page for the offer WEM priced; a retailer URL found elsewhere may be a different listing or price. The same links are in this array and, when a host renders one, in the card.'}, 'offers': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link to the retailer page for this offer. WEM never takes payment.'}, 'brand': {'type': ['string', 'null']}, 'image': {'type': ['string', 'null']}, 'price': {'type': ['number', 'null'], 'description': 'Indicative price. The retailer sets the final price at checkout. Null, with `priceNote`, when WEM may not show this listing’s price: the note stands in place of a figure.'}, 'title': {'type': 'string'}, 'rating': {'type': ['number', 'null']}, 'seller': {'type': ['string', 'null']}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string', 'description': 'retailer is a named shop (Boots, Currys). marketplace is eBay/AliExpress/Temu-style parallel listings. A marketplace cluster is not a set of competing authorised retailers.'}, 'inStock': {'type': ['boolean', 'null']}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}, 'provider': {'type': 'string', 'description': 'Retailer slug, e.g. "ebay", "currys".'}, 'shipping': {'type': ['object', 'null'], 'properties': {'cost': {'type': ['number', 'null']}, 'free': {'type': 'boolean'}, 'estimate': {'type': ['string', 'null'], 'description': 'Delivery window when the feed stated one.'}}}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'priceNote': {'type': 'string', 'description': 'Present only when `price` is null: the words that stand in its place, e.g. "See price at Amazon". An Amazon price is shown only when Amazon’s API supplied it just now.'}, 'unitPrice': {'type': 'object', 'properties': {'per': {'enum': ['100ml', 'litre', '100g', 'kg', 'item'], 'type': 'string'}, 'amount': {'type': 'number'}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}}, 'description': 'Price per 100ml, 100g, litre, kg or item, from the size this row\'s title states. Present only when the rows differ in size, in one unit across all of them, and only for things bought by the amount (beauty, food, supplements), never an appliance\'s capacity. Across sizes, value is compared on these, not on the prices: a smaller size is not cheaper because its price is lower. It reads beside the price ("£29.95, £99.83 per 100ml"). Absent does not mean the price is per unit.'}, 'lastSeenAt': {'type': ['string', 'null'], 'description': 'When WEM last READ this price from the retailer or a datafeed — the same reading `priceAgeDays` counts from, so the two always agree. Null means WEM cannot date the price: it is undated, not current.'}, 'priceStatus': {'enum': ['current', 'stale', 'undated'], 'type': 'string', 'description': '`current`: WEM read this price within the last 14 days; only a current price may lead, be called the cheapest or lowest, be compared or enter a saving. `stale`: read longer ago. `undated`: WEM cannot say when. Those two read as "last seen £X on 8 Sep" or "price not dated", come after the current ones, and are not compared. Absent on a row a provider answered just now.'}, 'reviewCount': {'type': ['number', 'null']}, 'priceAgeDays': {'type': ['number', 'null'], 'description': 'Calendar days (UK time) since WEM last READ this price: 0 read today, 1 yesterday. Null means WEM cannot say. Null is undated, not current.'}, 'priceRefresh': {'enum': ['live-api', 'feed', 'none'], 'type': 'string', 'description': 'What re-reads this retailer’s prices: `live-api` a product-lookup API, `feed` a partner datafeed, `none` nothing on a schedule. `none` means the figure will not move on its own however long it sits ; `priceAgeDays` dates it.'}, 'priceQualifier': {'enum': ['from'], 'type': 'string', 'description': 'Present when `price` is the OPENING price of a range, not the price of this item: a multi-variation listing where the seller advertises its cheapest variant and the shopper picks a size on the page. It reads as "from £X"; it is not the item\'s price or the cheapest. Absent means the price is firm for the row as described.'}}}, 'description': 'Current prices first (`priceStatus`), each group ascending by price; a stale or undated row is listed, never compared. Barcode, slug and WEM ID rows are the product. A title match is inferred; `identity.strength` says which.'}, 'reason': {'type': 'string', 'description': 'Present only when `found` is false: which identifier missed, and why. When `unavailable` is true this describes the outage rather than a missing product ; it is the reason the lookup failed, not a fact about the product.'}, 'search': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'reason': {'type': 'string'}, 'markdown': {'type': 'string', 'description': 'The same link, pre-formatted.'}}, 'description': "Present when this result names no offer. `url` is WEM's results page for the query and `markdown` is the same link, pre-formatted. WEM searches retailers live on that page, including shops it holds no affiliate programme with, so an empty or withheld result here is not evidence the product is unavailable or unpriced."}, 'source': {'type': 'string'}, 'product': {'type': 'object', 'required': ['slug', 'title'], 'properties': {'gtin': {'type': ['string', 'null'], 'description': 'The barcode identity was resolved on.'}, 'slug': {'type': 'string'}, 'brand': {'type': ['string', 'null']}, 'image': {'type': ['string', 'null'], 'description': 'Product photo, served from wem3.ai. Null when none is available.'}, 'title': {'type': 'string'}, 'wem_id': {'type': ['string', 'null'], 'description': 'WEM ID of this active product. Null when unknown.'}}}, 'ranking': {'type': 'object', 'properties': {'basis': {'type': 'string'}, 'reason': {'type': 'string'}, 'parameters': {'type': 'string', 'description': 'The published ranking parameters.'}}, 'description': 'Why the offers are in this order. Offers are ordered by price, lowest first; affiliate commission is not an input.'}, 'coverage': {'type': 'object', 'properties': {'low': {'type': 'number'}, 'high': {'type': 'number'}, 'kind': {'enum': ['marketplace_only'], 'type': 'string'}, 'currency': {'type': 'string'}, 'listings': {'type': 'number'}, 'provider': {'type': 'string', 'description': 'ebay, aliexpress, or marketplace when mixed.'}}, 'description': 'Present when surviving rows include a marketplace cluster at similar prices. That is not a retail floor — the cheapest marketplace listing is not the deal. The listings stay in the payload, each with its url. `next`, when present, is the Chrome extension page for shops WEM does not yet hold as partners.'}, 'currency': {'type': ['string', 'null']}, 'degraded': {'type': 'object', 'properties': {'note': {'type': 'string'}, 'skipped': {'type': 'array', 'items': {'type': 'string'}}}, 'description': 'Present when this call hit its time budget and skipped enrichment. The offers returned are COMPLETE — only the extras were dropped. A missing catalogue block or missing observed retailers does not mean WEM holds nothing, and no retry is needed.'}, 'filtered': {'type': ['object', 'null'], 'description': 'Offers of this product WEM held back, tallied by reason. "Priced far below this product’s other offers" is a marketplace listing under 40% of what the product sells for elsewhere — the shape of a counterfeit, a part or a mislisted variant. Those prices are not in `offers`, `lowPrice`, `links`, `summary` or `priceHistory.low`: none is the cheapest, a deal or the 90-day low. The tally says how many were held back.', 'additionalProperties': {'type': 'number'}}, 'identity': {'type': ['object', 'null'], 'properties': {'method': {'enum': ['gtin', 'slug', 'listing', 'title'], 'type': 'string'}, 'strength': {'enum': ['exact', 'catalogued', 'inferred'], 'type': 'string', 'description': 'exact = barcode; catalogued = a WEM key or listing id; inferred = matched on the product name, MPN or SKU and still a guess.'}}, 'description': 'How the shopper’s words reached this product. On `inferred`, WEM matched it by name (not by barcode) and the identity is not confirmed, even when `identityBasis` is `barcode`; on `exact`, the barcode itself resolved it.'}, 'lowPrice': {'type': ['number', 'null'], 'description': 'Lowest CURRENT price in `offers` (read within 14 days). Null when no price is current or WEM holds none it may quote ; it is never taken from a stale or undated row, or from `unpriced`.'}, 'nextTool': {'type': 'object', 'properties': {'tool': {'enum': ['search_products'], 'type': 'string'}, 'query': {'type': 'string'}}, 'description': 'Present only when `found` is false. It names `search_products` and the query. A named model that misses the catalogue is the ordinary case; the live search is a separate lookup.'}, 'unpriced': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link. The full URL; a shortened form is a different link.'}, 'title': {'type': 'string'}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string'}, 'provider': {'type': 'string'}, 'priceNote': {'type': 'string', 'description': 'What stands where a price would be, e.g. "See price at Amazon".'}}}, 'description': 'Listings whose price WEM may not show — today, Amazon rows Amazon’s API did not price just now. The row carries `priceNote` (e.g. "See price at Amazon") in place of a figure. No price is stated, estimated or compared for one; it is not the cheapest and is not counted in a lowest price or a saving.'}, 'highPrice': {'type': ['number', 'null'], 'description': 'Highest current price in `offers`; null with lowPrice.'}, 'sameModel': {'type': 'array', 'items': {'type': 'object', 'required': ['model', 'relation', 'differences', 'maker', 'checkedOn', 'summary'], 'properties': {'url': {'type': ['string', 'null'], 'description': "WEM's comparison for that model, not a shop."}, 'maker': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'host': {'type': 'string'}, 'says': {'type': 'string', 'description': "The page's words, as checked."}}, 'description': "The maker's own page that says so: the proof. WEM is not the source of the claim."}, 'model': {'type': 'string', 'description': 'The other model code, as the maker writes it.'}, 'summary': {'type': 'string', 'description': 'WEM’s words for it, written to be quoted as they are.'}, 'cheapest': {'type': ['object', 'null'], 'properties': {'shop': {'type': 'string'}, 'price': {'type': 'number'}, 'currency': {'type': 'string'}, 'priceAgeDays': {'type': ['number', 'null'], 'description': 'Days since WEM read that price. Null means undated.'}}, 'description': "The other model's cheapest named shop. Null when no named shop has an in-stock price for it. `priceAgeDays` gives its age; without one it is not current."}, 'relation': {'enum': ['identical', 'differs'], 'type': 'string', 'description': '`identical`: the maker says it is the same product. `differs`: the same product except `differences`; not like for like.'}, 'checkedOn': {'type': 'string', 'description': 'When a person at WEM read the maker’s page (YYYY-MM-DD).'}, 'differences': {'type': 'array', 'items': {'type': 'string'}, 'description': 'What the maker says differs. Empty when identical.'}}}, 'description': "Present only when the maker's own page says another model code is this product and a person at WEM has checked it. These are NOT offers for the product asked about: they are not part of `offers`, and none is this product's lowest price or the best deal. On verify_offer they are not part of the check: `verdict`, `cheapest`, `betterBy`, `summary` and the receipt are about the product asked about, and a cheaper sister code never makes the claimed price wrong. `summary` is written to be quoted as it is. `maker.host` is the source of the claim. `url` is WEM's comparison for that model, not a shop. When `relation` is `differs`, the `differences` are what the maker says differs, and its price is not a saving. Absent is not evidence that no equivalent exists."}, 'disclosure': {'type': 'string', 'description': 'WEM’s affiliate disclosure for this answer, written to be quoted as it is. Its wording changes with the rows: it states whether every outbound link is affiliate-tracked, only some are, or none are. A version from an earlier answer may not fit this one: a row marked `affiliate: false` earns WEM nothing.'}, 'unavailable': {'type': 'boolean', 'description': 'Present and true only when WEM could not reach its catalogue at all. `found` is false for the same reason it is on an ordinary miss, so the two are indistinguishable without this flag. When it is set, WEM does not know whether it holds the product. The lookup could not be completed; it does not mean WEM has no offers or no price for it. `nextTool` is still present, because the live retailer search does not depend on the catalogue.'}, 'priceHistory': {'type': 'object', 'properties': {'low': {'type': ['number', 'null']}, 'days': {'type': 'number'}}, 'description': 'The 90-day low, for telling a real discount from a repackaged one.'}, 'identityBasis': {'enum': ['barcode', 'curated-grouping'], 'type': 'string', 'description': 'How this product’s offers are grouped — NOT how the shopper’s words found the product; that is `identity`. `barcode`: the product carries a GTIN, so every offer here is that same item. `curated-grouping`: it carries none, and the grouping is an inference. This field does not make a result a barcode match: when `identity.strength` is `inferred`, WEM matched the product by name.'}, 'lastConfirmedAt': {'type': ['string', 'null'], 'description': 'When WEM last actually read any price in this answer. Null means none of them can be dated, so the answer is not current.'}}, 'description': 'The retailer offers WEM holds for one catalogue product, current prices first and each group cheapest first. When `found` is false WEM simply does not hold this product yet — that is a normal answer, not a failure, and it says nothing about whether the product exists or what it costs. `nextTool` then names `search_products` and the query. An empty catalogue result is not a statement that the product is unavailable or unpriced; the live retailer search is a separate lookup and routinely finds supply this catalogue has not ingested.'}
compare_products
Compare several products
Lays 2 to 5 listings from earlier search results side by side in `comparison`: each listing's price and currency, and its rating, shipping and features where the retailer source supplies them (many listings carry none). Each item needs the listing's `provider` and its `id` as `product_id`. Listings that cannot be found are left out, and fewer than two found is an error. Prices stay in each listing's own currency.
Lecture seule Accès externe
Schéma d’entrée
{'type': 'object', 'required': ['products'], 'properties': {'products': {'type': 'array', 'items': {'type': 'object', 'required': ['provider', 'product_id'], 'properties': {'provider': {'type': 'string'}, 'product_id': {'type': 'string'}}}, 'maxItems': 5, 'minItems': 2, 'description': '2 to 5 listings, each with `provider` and `product_id` as given in a search result.'}}}
Schéma de sortie
{'type': 'object', 'required': ['comparison', 'count', 'disclosure'], 'properties': {'count': {'type': 'number'}, 'comparison': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link to the retailer page for this offer. WEM never takes payment.'}, 'brand': {'type': ['string', 'null']}, 'image': {'type': ['string', 'null']}, 'price': {'type': ['number', 'null'], 'description': 'Indicative price. The retailer sets the final price at checkout. Null, with `priceNote`, when WEM may not show this listing’s price: the note stands in place of a figure.'}, 'title': {'type': 'string'}, 'badges': {'type': ['array', 'null'], 'items': {'type': 'string'}}, 'rating': {'type': ['number', 'null']}, 'seller': {'type': ['string', 'null']}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string', 'description': 'retailer is a named shop (Boots, Currys). marketplace is eBay/AliExpress/Temu-style parallel listings. A marketplace cluster is not a set of competing authorised retailers.'}, 'inStock': {'type': ['boolean', 'null']}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}, 'features': {'type': ['array', 'null'], 'items': {'type': 'string'}}, 'provider': {'type': 'string', 'description': 'Retailer slug, e.g. "ebay", "currys".'}, 'shipping': {'type': ['object', 'null'], 'properties': {'cost': {'type': ['number', 'null']}, 'free': {'type': 'boolean'}, 'estimate': {'type': ['string', 'null'], 'description': 'Delivery window when the feed stated one.'}}}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'priceNote': {'type': 'string', 'description': 'Present only when `price` is null: the words that stand in its place, e.g. "See price at Amazon". An Amazon price is shown only when Amazon’s API supplied it just now.'}, 'unitPrice': {'type': 'object', 'properties': {'per': {'enum': ['100ml', 'litre', '100g', 'kg', 'item'], 'type': 'string'}, 'amount': {'type': 'number'}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}}, 'description': 'Price per 100ml, 100g, litre, kg or item, from the size this row\'s title states. Present only when the rows differ in size, in one unit across all of them, and only for things bought by the amount (beauty, food, supplements), never an appliance\'s capacity. Across sizes, value is compared on these, not on the prices: a smaller size is not cheaper because its price is lower. It reads beside the price ("£29.95, £99.83 per 100ml"). Absent does not mean the price is per unit.'}, 'priceStatus': {'enum': ['current', 'stale', 'undated'], 'type': 'string', 'description': '`current`: WEM read this price within the last 14 days; only a current price may lead, be called the cheapest or lowest, be compared or enter a saving. `stale`: read longer ago. `undated`: WEM cannot say when. Those two read as "last seen £X on 8 Sep" or "price not dated", come after the current ones, and are not compared. Absent on a row a provider answered just now.'}, 'reviewCount': {'type': ['number', 'null']}, 'priceQualifier': {'enum': ['from'], 'type': 'string', 'description': 'Present when `price` is the OPENING price of a range, not the price of this item: a multi-variation listing where the seller advertises its cheapest variant and the shopper picks a size on the page. It reads as "from £X"; it is not the item\'s price or the cheapest. Absent means the price is firm for the row as described.'}}}}, 'disclosure': {'type': 'string', 'description': 'WEM’s affiliate disclosure for this answer, written to be quoted as it is. Its wording changes with the rows: it states whether every outbound link is affiliate-tracked, only some are, or none are. A version from an earlier answer may not fit this one: a row marked `affiliate: false` earns WEM nothing.'}}}
find_lowest_price
Find the lowest listed price
Picks one listing for a kind of product within the shopper's constraints, from WEM's catalogue and a live retailer search (a current catalogue match answers without the live search). Candidates are first filtered to plausible matches, so an accessory, another size, an out-of-stock listing or one priced far below the product's other offers is not picked. With no `priorities`, or with `cheapest` first, the lowest price wins; `best_rated`, `free_shipping` and `fastest` (has a delivery estimate) are weighed in the order given, where listings carry ratings or delivery details, and can outrank a lower price. WEM's commission is not a factor. `recommendation` is null with a reason when nothing matched confidently, when the matches differ in size, or when only stale prices remain; when `coverage.kind` is `marketplace_only` it is null but `alternatives` still lists the listings. `recommendation.verified` is true when WEM has recently observed that price at the retailer.
Lecture seule Accès externe
Schéma d’entrée
{'type': 'object', 'required': ['query'], 'properties': {'query': {'type': 'string', 'description': 'One kind of product or product: a name, barcode, ASIN, WEM ID or wem3.ai/pl URL. A single query, not a list.'}, 'currency': {'type': 'string', 'description': "ISO 4217 code to quote in. Default GBP. Offers in other currencies are withheld, never converted. Pass the shopper's market explicitly — WEM does not infer currency or retailer market from IP."}, 'condition': {'type': 'string', 'description': 'Same effect as include_used: "any", "used" or "refurbished" also includes used and refurbished listings; any other value means new only.'}, 'max_price': {'type': 'number', 'description': 'Budget cap, in `currency`.'}, 'priorities': {'type': 'array', 'items': {'enum': ['cheapest', 'best_rated', 'free_shipping', 'fastest'], 'type': 'string'}, 'description': 'What matters most, in order. cheapest: lowest price. best_rated: higher rating. free_shipping: free delivery. fastest: states a delivery estimate. Weighed only where listings carry those details.'}, 'include_used': {'type': 'boolean', 'description': 'If true, include used and refurbished listings. Default false — a used item is a different good, not a cheaper one.'}}}
Schéma de sortie
{'type': 'object', 'required': ['recommendation', 'reason'], 'properties': {'next': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'reason': {'type': 'string'}, 'surface': {'enum': ['chrome_extension'], 'type': 'string'}}, 'description': "Present when WEM's set of offers is thin. chrome_extension is a page that compares the same product on any retailer page, including shops without an affiliate programme."}, 'score': {'type': 'number', 'description': 'Internal ranking score. Not a price and not a rating — do not quote it.'}, 'reason': {'type': 'string', 'description': 'Why this was picked, or why nothing was.'}, 'search': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'reason': {'type': 'string'}, 'markdown': {'type': 'string', 'description': 'The same link, pre-formatted.'}}, 'description': "Present when this result names no offer. `url` is WEM's results page for the query and `markdown` is the same link, pre-formatted. WEM searches retailers live on that page, including shops it holds no affiliate programme with, so an empty or withheld result here is not evidence the product is unavailable or unpriced."}, 'partial': {'type': 'boolean', 'description': 'True when the live retailer fan-out hit its 3-second budget and some providers had not answered. The recommendation is the lowest among those that did. Do not call it the market floor, and do not retry automatically.'}, 'coverage': {'type': 'object', 'properties': {'low': {'type': 'number'}, 'high': {'type': 'number'}, 'kind': {'enum': ['marketplace_only'], 'type': 'string'}, 'currency': {'type': 'string'}, 'listings': {'type': 'number'}, 'provider': {'type': 'string', 'description': 'ebay, aliexpress, or marketplace when mixed.'}}, 'description': 'Present when surviving rows include a marketplace cluster at similar prices. That is not a retail floor — the cheapest marketplace listing is not the deal. The listings stay in the payload, each with its url. `next`, when present, is the Chrome extension page for shops WEM does not yet hold as partners.'}, 'degraded': {'type': 'object', 'properties': {'note': {'type': 'string'}, 'skipped': {'type': 'array', 'items': {'type': 'string'}}}, 'description': 'Present when this call hit its time budget and skipped enrichment. The offers returned are COMPLETE — only the extras were dropped. A missing catalogue block or missing observed retailers does not mean WEM holds nothing, and no retry is needed.'}, 'filtered': {'type': ['object', 'null'], 'description': 'Withheld candidates tallied by reason (e.g. accessories, another model, a bundle or multipack, a replica, a listing priced far below the product’s other offers). Report this count rather than implying the search was exhaustive, and never quote a withheld listing’s price as the cheapest or as a deal.', 'additionalProperties': {'type': 'number'}}, 'disclosure': {'type': 'string', 'description': 'WEM’s affiliate disclosure for this answer, written to be quoted as it is. Its wording changes with the rows: it states whether every outbound link is affiliate-tracked, only some are, or none are. A version from an earlier answer may not fit this one: a row marked `affiliate: false` earns WEM nothing.'}, 'alternatives': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link to the retailer page for this offer. WEM never takes payment.'}, 'brand': {'type': ['string', 'null']}, 'image': {'type': ['string', 'null']}, 'price': {'type': ['number', 'null'], 'description': 'Indicative price. The retailer sets the final price at checkout. Null, with `priceNote`, when WEM may not show this listing’s price: the note stands in place of a figure.'}, 'title': {'type': 'string'}, 'rating': {'type': ['number', 'null']}, 'seller': {'type': ['string', 'null']}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string', 'description': 'retailer is a named shop (Boots, Currys). marketplace is eBay/AliExpress/Temu-style parallel listings. A marketplace cluster is not a set of competing authorised retailers.'}, 'inStock': {'type': ['boolean', 'null']}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}, 'provider': {'type': 'string', 'description': 'Retailer slug, e.g. "ebay", "currys".'}, 'shipping': {'type': ['object', 'null'], 'properties': {'cost': {'type': ['number', 'null']}, 'free': {'type': 'boolean'}, 'estimate': {'type': ['string', 'null'], 'description': 'Delivery window when the feed stated one.'}}}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'priceNote': {'type': 'string', 'description': 'Present only when `price` is null: the words that stand in its place, e.g. "See price at Amazon". An Amazon price is shown only when Amazon’s API supplied it just now.'}, 'unitPrice': {'type': 'object', 'properties': {'per': {'enum': ['100ml', 'litre', '100g', 'kg', 'item'], 'type': 'string'}, 'amount': {'type': 'number'}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}}, 'description': 'Price per 100ml, 100g, litre, kg or item, from the size this row\'s title states. Present only when the rows differ in size, in one unit across all of them, and only for things bought by the amount (beauty, food, supplements), never an appliance\'s capacity. Across sizes, value is compared on these, not on the prices: a smaller size is not cheaper because its price is lower. It reads beside the price ("£29.95, £99.83 per 100ml"). Absent does not mean the price is per unit.'}, 'priceStatus': {'enum': ['current', 'stale', 'undated'], 'type': 'string', 'description': '`current`: WEM read this price within the last 14 days; only a current price may lead, be called the cheapest or lowest, be compared or enter a saving. `stale`: read longer ago. `undated`: WEM cannot say when. Those two read as "last seen £X on 8 Sep" or "price not dated", come after the current ones, and are not compared. Absent on a row a provider answered just now.'}, 'reviewCount': {'type': ['number', 'null']}, 'priceQualifier': {'enum': ['from'], 'type': 'string', 'description': 'Present when `price` is the OPENING price of a range, not the price of this item: a multi-variation listing where the seller advertises its cheapest variant and the shopper picks a size on the page. It reads as "from £X"; it is not the item\'s price or the cheapest. Absent means the price is firm for the row as described.'}}}, 'description': 'Listings still worth showing, including when recommendation is null.'}, 'catalogMatch': {'type': ['object', 'null'], 'properties': {'slug': {'type': 'string'}, 'title': {'type': 'string'}, 'offers': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link to the retailer page for this offer. WEM never takes payment.'}, 'brand': {'type': ['string', 'null']}, 'image': {'type': ['string', 'null']}, 'price': {'type': ['number', 'null'], 'description': 'Indicative price. The retailer sets the final price at checkout. Null, with `priceNote`, when WEM may not show this listing’s price: the note stands in place of a figure.'}, 'title': {'type': 'string'}, 'rating': {'type': ['number', 'null']}, 'seller': {'type': ['string', 'null']}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string', 'description': 'retailer is a named shop (Boots, Currys). marketplace is eBay/AliExpress/Temu-style parallel listings. A marketplace cluster is not a set of competing authorised retailers.'}, 'inStock': {'type': ['boolean', 'null']}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}, 'provider': {'type': 'string', 'description': 'Retailer slug, e.g. "ebay", "currys".'}, 'shipping': {'type': ['object', 'null'], 'properties': {'cost': {'type': ['number', 'null']}, 'free': {'type': 'boolean'}, 'estimate': {'type': ['string', 'null'], 'description': 'Delivery window when the feed stated one.'}}}, 'verified': {'type': 'boolean', 'description': 'True when WEM has recently observed this price on the retailer’s own surface. False means the identity is still catalogue-resolved but the price is indicative (partner feed or stale) — do not present it as verified.'}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'priceNote': {'type': 'string', 'description': 'Present only when `price` is null: the words that stand in its place, e.g. "See price at Amazon". An Amazon price is shown only when Amazon’s API supplied it just now.'}, 'unitPrice': {'type': 'object', 'properties': {'per': {'enum': ['100ml', 'litre', '100g', 'kg', 'item'], 'type': 'string'}, 'amount': {'type': 'number'}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}}, 'description': 'Price per 100ml, 100g, litre, kg or item, from the size this row\'s title states. Present only when the rows differ in size, in one unit across all of them, and only for things bought by the amount (beauty, food, supplements), never an appliance\'s capacity. Across sizes, value is compared on these, not on the prices: a smaller size is not cheaper because its price is lower. It reads beside the price ("£29.95, £99.83 per 100ml"). Absent does not mean the price is per unit.'}, 'lastSeenAt': {'type': ['string', 'null'], 'description': 'When WEM last READ this price from the retailer or a datafeed — the same reading `priceAgeDays` counts from, so the two always agree. Null means WEM cannot date the price: it is undated, not current.'}, 'priceStatus': {'enum': ['current', 'stale', 'undated'], 'type': 'string', 'description': '`current`: WEM read this price within the last 14 days; only a current price may lead, be called the cheapest or lowest, be compared or enter a saving. `stale`: read longer ago. `undated`: WEM cannot say when. Those two read as "last seen £X on 8 Sep" or "price not dated", come after the current ones, and are not compared. Absent on a row a provider answered just now.'}, 'reviewCount': {'type': ['number', 'null']}, 'priceAgeDays': {'type': ['number', 'null'], 'description': 'Calendar days (UK time) since WEM last READ this price: 0 read today, 1 yesterday. Null means WEM cannot say. Null is undated, not current.'}, 'priceRefresh': {'enum': ['live-api', 'feed', 'none'], 'type': 'string', 'description': 'What re-reads this retailer’s prices: `live-api` a product-lookup API, `feed` a partner datafeed, `none` nothing on a schedule. `none` means the figure will not move on its own however long it sits ; `priceAgeDays` dates it.'}, 'priceQualifier': {'enum': ['from'], 'type': 'string', 'description': 'Present when `price` is the OPENING price of a range, not the price of this item: a multi-variation listing where the seller advertises its cheapest variant and the shopper picks a size on the page. It reads as "from £X"; it is not the item\'s price or the cheapest. Absent means the price is firm for the row as described.'}}}}, 'source': {'type': 'string'}, 'currency': {'type': ['string', 'null']}, 'identity': {'type': ['object', 'null'], 'properties': {'method': {'enum': ['gtin', 'slug', 'listing', 'title'], 'type': 'string'}, 'strength': {'enum': ['exact', 'catalogued', 'inferred'], 'type': 'string', 'description': 'exact = barcode; catalogued = a WEM key or listing id; inferred = matched on the product name, MPN or SKU and still a guess.'}}, 'description': 'How the shopper’s words reached this product. On `inferred`, WEM matched it by name (not by barcode) and the identity is not confirmed, even when `identityBasis` is `barcode`; on `exact`, the barcode itself resolved it.'}, 'lowPrice': {'type': ['number', 'null'], 'description': 'Lowest CURRENT price in `offers` (priceStatus `current`). Null when none is current: never fill it from an older or undated row.'}, 'unpriced': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link. The full URL; a shortened form is a different link.'}, 'title': {'type': 'string'}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string'}, 'provider': {'type': 'string'}, 'priceNote': {'type': 'string', 'description': 'What stands where a price would be, e.g. "See price at Amazon".'}}}, 'description': 'Listings whose price WEM may not show — today, Amazon rows Amazon’s API did not price just now. The row carries `priceNote` (e.g. "See price at Amazon") in place of a figure. No price is stated, estimated or compared for one; it is not the cheapest and is not counted in a lowest price or a saving.'}, 'productPage': {'type': 'string'}, 'identityBasis': {'enum': ['barcode', 'curated-grouping'], 'type': 'string', 'description': 'What this block’s identity rests on. `barcode` — the canonical product carries a GTIN and these offers are the same physical item. `curated-grouping` — it carries none, so the grouping is an inference of the same kind a title match is; do not describe it to the user as barcode-confirmed, and do not let it outrank a cheaper row in `products` on price alone. This is how the offers are grouped, not how the query matched the product — see `identity`.'}, 'lastConfirmedAt': {'type': ['string', 'null'], 'description': 'When WEM last actually read any price in this block. Null means none of them can be dated — say so rather than implying the block is current.'}, 'cheaperElsewhere': {'type': ['object', 'null'], 'properties': {'note': {'type': 'string', 'description': 'Plain-language restatement, safe to relay.'}, 'identity': {'enum': ['inferred'], 'type': 'string', 'description': 'Always `inferred` — matched on title, not barcode. Say so when quoting it.'}, 'verified': {'type': 'boolean', 'description': 'Always false.'}, 'savingVsCatalogue': {'type': 'number', 'description': 'How much cheaper this row is than the block’s lowest offer.'}}, 'description': 'Present only on a `curated-grouping` block that a live row in `products` undercuts. WEM is telling you its own catalogue block is not the best price it found. Quote this row as the cheaper option with its identity stated as unconfirmed; never present the catalogMatch price as the lowest when this is set.'}}, 'description': 'Offers WEM holds under one catalogue product. Check `identityBasis`: on `barcode` the product carries a GTIN and every offer here is that same item, so prefer them and cite their prices over anything in `products`. On `curated-grouping` the product carries no barcode, the grouping is an inference like any title match, and a cheaper row in `products` may well be the same item — see `cheaperElsewhere`. Whether the shopper’s words reached this product by barcode or by name is `identity`, a separate question: on `inferred`, say WEM matched it by name.'}, 'recommendation': {'type': ['object', 'null'], 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link to the retailer page for this offer. WEM never takes payment.'}, 'brand': {'type': ['string', 'null']}, 'image': {'type': ['string', 'null']}, 'price': {'type': ['number', 'null'], 'description': 'Indicative price. The retailer sets the final price at checkout. Null, with `priceNote`, when WEM may not show this listing’s price: the note stands in place of a figure.'}, 'title': {'type': 'string'}, 'rating': {'type': ['number', 'null']}, 'seller': {'type': ['string', 'null']}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string', 'description': 'retailer is a named shop (Boots, Currys). marketplace is eBay/AliExpress/Temu-style parallel listings. A marketplace cluster is not a set of competing authorised retailers.'}, 'inStock': {'type': ['boolean', 'null']}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}, 'provider': {'type': 'string', 'description': 'Retailer slug, e.g. "ebay", "currys".'}, 'shipping': {'type': ['object', 'null'], 'properties': {'cost': {'type': ['number', 'null']}, 'free': {'type': 'boolean'}, 'estimate': {'type': ['string', 'null'], 'description': 'Delivery window when the feed stated one.'}}}, 'verified': {'type': 'boolean', 'description': 'True when WEM resolved this offer’s identity AND recently observed its price on the retailer’s surface. A recommendation can be unverified and still the best candidate — report it as such.'}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'priceNote': {'type': 'string', 'description': 'Present only when `price` is null: the words that stand in its place, e.g. "See price at Amazon". An Amazon price is shown only when Amazon’s API supplied it just now.'}, 'unitPrice': {'type': 'object', 'properties': {'per': {'enum': ['100ml', 'litre', '100g', 'kg', 'item'], 'type': 'string'}, 'amount': {'type': 'number'}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}}, 'description': 'Price per 100ml, 100g, litre, kg or item, from the size this row\'s title states. Present only when the rows differ in size, in one unit across all of them, and only for things bought by the amount (beauty, food, supplements), never an appliance\'s capacity. Across sizes, value is compared on these, not on the prices: a smaller size is not cheaper because its price is lower. It reads beside the price ("£29.95, £99.83 per 100ml"). Absent does not mean the price is per unit.'}, 'priceStatus': {'enum': ['current', 'stale', 'undated'], 'type': 'string', 'description': '`current`: WEM read this price within the last 14 days; only a current price may lead, be called the cheapest or lowest, be compared or enter a saving. `stale`: read longer ago. `undated`: WEM cannot say when. Those two read as "last seen £X on 8 Sep" or "price not dated", come after the current ones, and are not compared. Absent on a row a provider answered just now.'}, 'reviewCount': {'type': ['number', 'null']}, 'priceQualifier': {'enum': ['from'], 'type': 'string', 'description': 'Present when `price` is the OPENING price of a range, not the price of this item: a multi-variation listing where the seller advertises its cheapest variant and the shopper picks a size on the page. It reads as "from £X"; it is not the item\'s price or the cheapest. Absent means the price is firm for the row as described.'}}, 'description': 'The single lowest-priced plausible match, or null when nothing matched confidently.'}, 'liveSearchSkipped': {'type': 'boolean', 'description': 'True when a catalogue hit answered the question without spending retailer API quota.'}, 'pending_providers': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Providers still running when the budget expired. Present only with partial. Their prices are not in this answer.'}}, 'description': 'A null `recommendation` with `coverage.kind` marketplace_only still has listings in `alternatives`. A null with no alternatives is a genuine miss. A genuine miss is not a suggestion.'}
get_categories
List shopping categories
Lists the six broad shopping categories WEM covers (electronics, fashion, beauty, home, sports, collectibles), each with example products, plus the retailer sources currently enabled and the default currency (GBP). Use it to help a shopper narrow a vague request. It returns no prices, and the category names are labels for the shopper, not filter values.
Lecture seule
Schéma d’entrée
{'type': 'object', 'properties': {}}
Schéma de sortie
{'type': 'object', 'required': ['categories', 'providers', 'currency'], 'properties': {'currency': {'type': 'string'}, 'providers': {'type': 'array', 'items': {'type': 'object', 'properties': {'name': {'type': 'string'}, 'displayName': {'type': 'string'}}}, 'description': 'Retailers currently enabled. WEM compares only feeds it is licensed to use.'}, 'categories': {'type': 'array', 'items': {'type': 'object', 'properties': {'name': {'type': 'string'}, 'examples': {'type': 'string'}}}}}}
get_evidence_receipt
Look up a verification receipt by id
Fetches an evidence receipt by its id (wem-evr- followed by 32 hex characters), as issued with a verify_offer result. Returns the receipt's fields: verdict, observed_at, source, amount, currency and amount_minor, identity_method, verifier, standardVersion and issuedAt, with `signed` true and an HMAC `signature` when WEM signed it. It holds the citation, not the product's offers. A receipt issued moments ago may not be fetchable yet.
Lecture seule
Schéma d’entrée
{'type': 'object', 'required': ['id'], 'properties': {'id': {'type': 'string', 'description': "Receipt id (wem-evr- followed by 32 hex characters), as returned in a verify_offer result's receipt.id."}}}
Schéma de sortie
{'type': 'object', 'required': ['id', 'standardVersion', 'observed_at', 'source', 'verifier', 'signed'], 'properties': {'id': {'type': 'string'}, 'amount': {'type': ['number', 'null']}, 'signed': {'type': 'boolean'}, 'source': {'type': 'string'}, 'verdict': {'type': 'string'}, 'currency': {'type': ['string', 'null']}, 'issuedAt': {'type': 'string'}, 'verifier': {'type': 'string'}, 'signature': {'type': ['string', 'null']}, 'observed_at': {'type': 'string'}, 'amount_minor': {'type': ['number', 'null']}, 'identity_method': {'type': ['string', 'null']}, 'standardVersion': {'type': 'string'}}, 'description': 'A previously issued evidence receipt, looked up by id.'}
get_product
Get one product
Returns one product's details. Given `provider` and `product_id` from a search result, it returns that listing as its retailer source supplies it (title, price and link, with rating, shipping or features where the source has them); when the source cannot be reached it falls back to WEM's catalogue record of the listing, and an unknown listing is an error. Given `wem_id`, it returns that catalogue product with the retailer offers WEM holds for it.
Lecture seule Accès externe
Schéma d’entrée
{'type': 'object', 'anyOf': [{'required': ['wem_id']}, {'required': ['provider', 'product_id']}], 'properties': {'wem_id': {'type': 'string', 'description': 'WEM ID (W + 10 Crockford characters + check). Active catalogue products only.'}, 'provider': {'type': 'string', 'description': 'Retailer source of the listing, as given in the search result (e.g. "ebay", "awin").'}, 'product_id': {'type': 'string', 'description': "The listing's `id` from the search result."}}}
Schéma de sortie
{'type': 'object', 'required': ['url', 'disclosure'], 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link to the retailer page for this offer. WEM never takes payment.'}, 'brand': {'type': ['string', 'null']}, 'image': {'type': ['string', 'null']}, 'price': {'type': ['number', 'null'], 'description': 'Indicative price. The retailer sets the final price at checkout. Null, with `priceNote`, when WEM may not show this listing’s price: the note stands in place of a figure.'}, 'title': {'type': 'string'}, 'badges': {'type': ['array', 'null'], 'items': {'type': 'string'}}, 'rating': {'type': ['number', 'null']}, 'seller': {'type': ['string', 'null']}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string', 'description': 'retailer is a named shop (Boots, Currys). marketplace is eBay/AliExpress/Temu-style parallel listings. A marketplace cluster is not a set of competing authorised retailers.'}, 'inStock': {'type': ['boolean', 'null']}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}, 'features': {'type': ['array', 'null'], 'items': {'type': 'string'}}, 'provider': {'type': 'string', 'description': 'Retailer slug, e.g. "ebay", "currys".'}, 'shipping': {'type': ['object', 'null'], 'properties': {'cost': {'type': ['number', 'null']}, 'free': {'type': 'boolean'}, 'estimate': {'type': ['string', 'null'], 'description': 'Delivery window when the feed stated one.'}}}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'priceNote': {'type': 'string', 'description': 'Present only when `price` is null: the words that stand in its place, e.g. "See price at Amazon". An Amazon price is shown only when Amazon’s API supplied it just now.'}, 'unitPrice': {'type': 'object', 'properties': {'per': {'enum': ['100ml', 'litre', '100g', 'kg', 'item'], 'type': 'string'}, 'amount': {'type': 'number'}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}}, 'description': 'Price per 100ml, 100g, litre, kg or item, from the size this row\'s title states. Present only when the rows differ in size, in one unit across all of them, and only for things bought by the amount (beauty, food, supplements), never an appliance\'s capacity. Across sizes, value is compared on these, not on the prices: a smaller size is not cheaper because its price is lower. It reads beside the price ("£29.95, £99.83 per 100ml"). Absent does not mean the price is per unit.'}, 'disclosure': {'type': 'string', 'description': 'WEM’s affiliate disclosure for this answer, written to be quoted as it is. Its wording changes with the rows: it states whether every outbound link is affiliate-tracked, only some are, or none are. A version from an earlier answer may not fit this one: a row marked `affiliate: false` earns WEM nothing.'}, 'description': {'type': ['string', 'null']}, 'priceStatus': {'enum': ['current', 'stale', 'undated'], 'type': 'string', 'description': '`current`: WEM read this price within the last 14 days; only a current price may lead, be called the cheapest or lowest, be compared or enter a saving. `stale`: read longer ago. `undated`: WEM cannot say when. Those two read as "last seen £X on 8 Sep" or "price not dated", come after the current ones, and are not compared. Absent on a row a provider answered just now.'}, 'reviewCount': {'type': ['number', 'null']}, 'priceQualifier': {'enum': ['from'], 'type': 'string', 'description': 'Present when `price` is the OPENING price of a range, not the price of this item: a multi-variation listing where the seller advertises its cheapest variant and the shopper picks a size on the page. It reads as "from £X"; it is not the item\'s price or the cheapest. Absent means the price is firm for the row as described.'}}, 'description': 'Full provider record for one product, plus a WEM tracked link.'}
lookup_products
Look up several products by barcode
Looks up to 20 product identifiers in one call: barcodes (EAN/UPC/GTIN), Amazon ASINs, WEM IDs, catalogue slugs or wem3.ai/pl URLs. Each row has a status: found (WEM's catalogue holds it; the row gives its number of retailer offers, the lowest current price at a named retailer in the shopper's currency, a marketplace low where there is one, and a link to WEM's product page), not_found (WEM does not hold it yet, which says nothing about whether it exists or has a price), unrecognised (not an identifier, such as a product name) or not_checked (not reached in this call, so not a miss). Identifiers beyond 20 are counted in `overLimit`.
Lecture seule
Schéma d’entrée
{'type': 'object', 'required': ['identifiers'], 'properties': {'currency': {'type': 'string', 'description': "ISO 4217 code for the shopper's market. Default GBP. Lowest prices are quoted in this currency only, never converted; a product WEM holds only in another currency comes back found with lowPrice null and heldInCurrencies set."}, 'identifiers': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 20, 'minItems': 1, 'description': '1-20 barcodes (EAN-13, UPC-A, EAN-8, GTIN-14), Amazon ASINs, WEM IDs, catalogue slugs or wem3.ai/pl URLs. Mixed kinds are fine; a comma-separated string is also accepted. Duplicates are looked up once. Each entry must be the identifier alone: not a product name, and not a name with a barcode in it.'}}}
Schéma de sortie
{'type': 'object', 'required': ['results', 'counts', 'currency', 'links', 'disclosure'], 'properties': {'next': {'type': 'object', 'properties': {'tool': {'type': 'string'}, 'reason': {'type': 'string'}}, 'description': 'The WEM tool that answers the follow-up question, and what to pass it.'}, 'links': {'type': 'array', 'items': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'input': {'type': 'string'}, 'title': {'type': 'string'}, 'markdown': {'type': 'string'}}}, 'description': 'The WEM product-page links for found rows, pre-formatted to quote. Give these to the user when you name a found product.'}, 'counts': {'type': 'object', 'properties': {'found': {'type': 'number'}, 'notFound': {'type': 'number'}, 'overLimit': {'type': 'number', 'description': 'Identifiers beyond the per-call limit, not looked up.'}, 'requested': {'type': 'number'}, 'duplicates': {'type': 'number'}, 'notChecked': {'type': 'number'}, 'unrecognised': {'type': 'number'}}}, 'results': {'type': 'array', 'items': {'type': 'object', 'required': ['input', 'kind', 'status'], 'properties': {'kind': {'enum': ['gtin', 'asin', 'wem_id', 'slug', 'unrecognised'], 'type': 'string'}, 'note': {'type': 'string', 'description': 'Why a row is not found, unrecognised or not checked. Quote it rather than paraphrase.'}, 'input': {'type': 'string', 'description': 'The identifier as sent, for joining rows back.'}, 'status': {'enum': ['found', 'not_found', 'unrecognised', 'not_checked'], 'type': 'string', 'description': 'not_found: WEM does not hold it yet — that is not a finding that the product does not exist or has no price. compare_offers and search_products are the lookups for it. not_checked: not reached in this call, and not a miss. unrecognised: not an identifier this tool reads (product names go to compare_offers).'}, 'product': {'type': 'object', 'required': ['slug', 'title', 'url'], 'properties': {'url': {'type': 'string', 'description': 'WEM product page listing every retailer WEM holds. The full URL; a shortened form is a different link.'}, 'gtin': {'type': ['string', 'null']}, 'slug': {'type': 'string'}, 'title': {'type': 'string'}, 'wem_id': {'type': 'string'}}}, 'currency': {'type': 'string'}, 'identity': {'type': ['object', 'null'], 'properties': {'method': {'enum': ['gtin', 'slug', 'listing', 'title'], 'type': 'string'}, 'strength': {'enum': ['exact', 'catalogued', 'inferred'], 'type': 'string'}}}, 'lowPrice': {'type': ['number', 'null'], 'description': 'Lowest current indicative price (read within 14 days) at a named retailer in `currency`. Null when WEM holds the product only in another currency (see heldInCurrencies) — never convert one yourself — only as marketplace listings, or with no current price (see note).'}, 'retailers': {'type': 'number', 'description': 'Distinct retailers holding it in `currency`. One retailer is a price, not a comparison — do not call it the cheapest.'}, 'lastConfirmedAt': {'type': ['string', 'null'], 'description': 'When WEM last actually read a price for this row. Null means none can be dated — say so.'}, 'heldInCurrencies': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Present when lowPrice is null: the currencies WEM does hold it in.'}, 'lowPriceRetailer': {'type': ['string', 'null']}, 'marketplaceListings': {'type': 'number'}, 'marketplaceLowPrice': {'type': 'number', 'description': 'Cheapest marketplace listing (eBay, AliExpress…), present only when it undercuts lowPrice or no named retailer holds the product. A seller’s price, not a retail floor: never quote it as the product’s price or the cheapest.'}}}}, 'currency': {'type': 'string'}, 'disclosure': {'type': 'string', 'description': 'WEM’s affiliate disclosure for this answer, written to be quoted as it is. Its wording changes with the rows: it states whether every outbound link is affiliate-tracked, only some are, or none are. A version from an earlier answer may not fit this one: a row marked `affiliate: false` earns WEM nothing.'}, 'unavailable': {'type': 'boolean', 'description': 'Present and true when WEM could not reach its catalogue. Rows it could not check are not_checked, not not_found — do not report them as products WEM lacks.'}, 'overLimitNote': {'type': 'string'}}, 'description': 'One row per distinct identifier, in the order sent. A row is a catalogue fact, not an offer: it says whether WEM holds the product and what the lowest price is, and links to WEM’s product page. Call compare_offers with product.slug for the retailer offers and their links.'}
search_products
Search products across retailers
Searches WEM's catalogue and its connected retailer sources for products matching a query. The query can be a product name or an identifier: a barcode (EAN/UPC/GTIN), an Amazon ASIN, an MPN, a merchant SKU that names one catalogue product, a WEM ID or a wem3.ai/pl/{slug} URL, and several identifiers may be comma-separated. When the query identifies a product WEM holds, a `catalogMatch` block (`catalogMatches` for several) gives that product's retailer offers; a barcode, ASIN, WEM ID or URL match skips the live retailer search, so `products` then holds catalogue offers only. Barcode, ASIN and slug matches are identity-resolved; MPN, SKU and title matches are inferred. Accessories, bundles, other models and listings priced far below the product's other offers are withheld and counted by reason in `filtered`.
Lecture seule Accès externe
Schéma d’entrée
{'type': 'object', 'required': ['query'], 'properties': {'gtin': {'type': 'string', 'description': 'A product barcode (EAN/UPC/GTIN) the host already has. When given, retailer sources are searched by this barcode instead of by the query words.'}, 'limit': {'type': 'number', 'description': 'How many listings to request from each retailer source (default 10, max 30). The combined list can hold more.'}, 'query': {'type': 'string', 'description': 'A product name, or an identifier: barcode (EAN/UPC/GTIN), ASIN, MPN, merchant SKU, WEM ID or wem3.ai/pl URL. Several identifiers may be comma-separated.'}, 'sort_by': {'enum': ['relevance', 'price_asc', 'price_desc', 'rating'], 'type': 'string', 'description': 'Order of the live retailer listings (default relevance). Not applied when the query identifies a product.'}, 'category': {'type': 'string', 'description': "Optional. Keeps only live retailer listings whose own category name matches this text exactly; catalogue matches ignore it. Leave it out unless the shopper names a retailer's category."}, 'currency': {'type': 'string', 'description': "ISO 4217 code for the shopper's market. Default GBP. Results and price filters use this currency."}, 'max_price': {'type': 'number', 'description': 'Highest price to include, in `currency`. Applies to retailer listings, not to `catalogMatch`.'}, 'min_price': {'type': 'number', 'description': 'Lowest price to include, in `currency`. Applies to retailer listings, not to `catalogMatch`.'}, 'providers': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Retailer sources to search live, e.g. ["ebay", "awin"]. Omit for all. Catalogue matches are not limited by it.'}}}
Schéma de sortie
{'type': 'object', 'required': ['products', 'totalResults', 'query', 'disclosure'], 'properties': {'next': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'reason': {'type': 'string'}, 'surface': {'enum': ['chrome_extension'], 'type': 'string'}}, 'description': "Present when WEM's set of offers is thin. chrome_extension is a page that compares the same product on any retailer page, including shops without an affiliate programme."}, 'query': {'type': 'string'}, 'search': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'reason': {'type': 'string'}, 'markdown': {'type': 'string', 'description': 'The same link, pre-formatted.'}}, 'description': "Present when this result names no offer. `url` is WEM's results page for the query and `markdown` is the same link, pre-formatted. WEM searches retailers live on that page, including shops it holds no affiliate programme with, so an empty or withheld result here is not evidence the product is unavailable or unpriced."}, 'partial': {'type': 'boolean', 'description': 'True when the live retailer fan-out hit its 3-second budget and some providers had not answered. The rows returned are real; the market may be wider. Ask again for the rest.'}, 'coverage': {'type': 'object', 'properties': {'low': {'type': 'number'}, 'high': {'type': 'number'}, 'kind': {'enum': ['marketplace_only'], 'type': 'string'}, 'currency': {'type': 'string'}, 'listings': {'type': 'number'}, 'provider': {'type': 'string', 'description': 'ebay, aliexpress, or marketplace when mixed.'}}, 'description': 'Present when surviving rows include a marketplace cluster at similar prices. That is not a retail floor — the cheapest marketplace listing is not the deal. The listings stay in the payload, each with its url. `next`, when present, is the Chrome extension page for shops WEM does not yet hold as partners.'}, 'degraded': {'type': 'object', 'properties': {'note': {'type': 'string'}, 'skipped': {'type': 'array', 'items': {'type': 'string'}}}, 'description': 'Present when this call hit its time budget and skipped enrichment. The offers returned are COMPLETE — only the extras were dropped. A missing catalogue block or missing observed retailers does not mean WEM holds nothing, and no retry is needed.'}, 'filtered': {'type': ['object', 'null'], 'description': 'Withheld candidates tallied by reason (e.g. accessories, another model, a bundle or multipack, a replica, a listing priced far below the product’s other offers). Report this count rather than implying the search was exhaustive, and never quote a withheld listing’s price as the cheapest or as a deal.', 'additionalProperties': {'type': 'number'}}, 'products': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link to the retailer page for this offer. WEM never takes payment.'}, 'brand': {'type': ['string', 'null']}, 'image': {'type': ['string', 'null']}, 'price': {'type': ['number', 'null'], 'description': 'Indicative price. The retailer sets the final price at checkout. Null, with `priceNote`, when WEM may not show this listing’s price: the note stands in place of a figure.'}, 'title': {'type': 'string'}, 'rating': {'type': ['number', 'null']}, 'seller': {'type': ['string', 'null']}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string', 'description': 'retailer is a named shop (Boots, Currys). marketplace is eBay/AliExpress/Temu-style parallel listings. A marketplace cluster is not a set of competing authorised retailers.'}, 'inStock': {'type': ['boolean', 'null']}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}, 'provider': {'type': 'string', 'description': 'Retailer slug, e.g. "ebay", "currys".'}, 'shipping': {'type': ['object', 'null'], 'properties': {'cost': {'type': ['number', 'null']}, 'free': {'type': 'boolean'}, 'estimate': {'type': ['string', 'null'], 'description': 'Delivery window when the feed stated one.'}}}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'priceNote': {'type': 'string', 'description': 'Present only when `price` is null: the words that stand in its place, e.g. "See price at Amazon". An Amazon price is shown only when Amazon’s API supplied it just now.'}, 'unitPrice': {'type': 'object', 'properties': {'per': {'enum': ['100ml', 'litre', '100g', 'kg', 'item'], 'type': 'string'}, 'amount': {'type': 'number'}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}}, 'description': 'Price per 100ml, 100g, litre, kg or item, from the size this row\'s title states. Present only when the rows differ in size, in one unit across all of them, and only for things bought by the amount (beauty, food, supplements), never an appliance\'s capacity. Across sizes, value is compared on these, not on the prices: a smaller size is not cheaper because its price is lower. It reads beside the price ("£29.95, £99.83 per 100ml"). Absent does not mean the price is per unit.'}, 'priceStatus': {'enum': ['current', 'stale', 'undated'], 'type': 'string', 'description': '`current`: WEM read this price within the last 14 days; only a current price may lead, be called the cheapest or lowest, be compared or enter a saving. `stale`: read longer ago. `undated`: WEM cannot say when. Those two read as "last seen £X on 8 Sep" or "price not dated", come after the current ones, and are not compared. Absent on a row a provider answered just now.'}, 'reviewCount': {'type': ['number', 'null']}, 'priceQualifier': {'enum': ['from'], 'type': 'string', 'description': 'Present when `price` is the OPENING price of a range, not the price of this item: a multi-variation listing where the seller advertises its cheapest variant and the shopper picks a size on the page. It reads as "from £X"; it is not the item\'s price or the cheapest. Absent means the price is firm for the row as described.'}}}}, 'unpriced': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link. The full URL; a shortened form is a different link.'}, 'title': {'type': 'string'}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string'}, 'provider': {'type': 'string'}, 'priceNote': {'type': 'string', 'description': 'What stands where a price would be, e.g. "See price at Amazon".'}}}, 'description': 'Listings whose price WEM may not show — today, Amazon rows Amazon’s API did not price just now. The row carries `priceNote` (e.g. "See price at Amazon") in place of a figure. No price is stated, estimated or compared for one; it is not the cheapest and is not counted in a lowest price or a saving.'}, 'disclosure': {'type': 'string', 'description': 'WEM’s affiliate disclosure for this answer, written to be quoted as it is. Its wording changes with the rows: it states whether every outbound link is affiliate-tracked, only some are, or none are. A version from an earlier answer may not fit this one: a row marked `affiliate: false` earns WEM nothing.'}, 'sizeSpread': {'type': 'object', 'properties': {'note': {'type': 'string'}, 'sizes': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The distinct sizes found, as the listings wrote them.'}, 'comparable': {'enum': [False], 'type': 'boolean'}}, 'description': 'Present when the returned rows are different sizes and the query named none, so price ordering is meaningless: the cheapest row is cheapest because it is less of the product. Do NOT name a cheapest, a lowest price, or a best deal across these rows. The size belongs beside every price. Where rows carry `unitPrice`, that is the like-for-like figure, and it is the figure to rank on when the question is which is better value. The rows are real listings, each with its url.'}, 'catalogMatch': {'type': ['object', 'null'], 'properties': {'slug': {'type': 'string'}, 'title': {'type': 'string'}, 'offers': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link to the retailer page for this offer. WEM never takes payment.'}, 'brand': {'type': ['string', 'null']}, 'image': {'type': ['string', 'null']}, 'price': {'type': ['number', 'null'], 'description': 'Indicative price. The retailer sets the final price at checkout. Null, with `priceNote`, when WEM may not show this listing’s price: the note stands in place of a figure.'}, 'title': {'type': 'string'}, 'rating': {'type': ['number', 'null']}, 'seller': {'type': ['string', 'null']}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string', 'description': 'retailer is a named shop (Boots, Currys). marketplace is eBay/AliExpress/Temu-style parallel listings. A marketplace cluster is not a set of competing authorised retailers.'}, 'inStock': {'type': ['boolean', 'null']}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}, 'provider': {'type': 'string', 'description': 'Retailer slug, e.g. "ebay", "currys".'}, 'shipping': {'type': ['object', 'null'], 'properties': {'cost': {'type': ['number', 'null']}, 'free': {'type': 'boolean'}, 'estimate': {'type': ['string', 'null'], 'description': 'Delivery window when the feed stated one.'}}}, 'verified': {'type': 'boolean', 'description': 'True when WEM has recently observed this price on the retailer’s own surface. False means the identity is still catalogue-resolved but the price is indicative (partner feed or stale) — do not present it as verified.'}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'priceNote': {'type': 'string', 'description': 'Present only when `price` is null: the words that stand in its place, e.g. "See price at Amazon". An Amazon price is shown only when Amazon’s API supplied it just now.'}, 'unitPrice': {'type': 'object', 'properties': {'per': {'enum': ['100ml', 'litre', '100g', 'kg', 'item'], 'type': 'string'}, 'amount': {'type': 'number'}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}}, 'description': 'Price per 100ml, 100g, litre, kg or item, from the size this row\'s title states. Present only when the rows differ in size, in one unit across all of them, and only for things bought by the amount (beauty, food, supplements), never an appliance\'s capacity. Across sizes, value is compared on these, not on the prices: a smaller size is not cheaper because its price is lower. It reads beside the price ("£29.95, £99.83 per 100ml"). Absent does not mean the price is per unit.'}, 'lastSeenAt': {'type': ['string', 'null'], 'description': 'When WEM last READ this price from the retailer or a datafeed — the same reading `priceAgeDays` counts from, so the two always agree. Null means WEM cannot date the price: it is undated, not current.'}, 'priceStatus': {'enum': ['current', 'stale', 'undated'], 'type': 'string', 'description': '`current`: WEM read this price within the last 14 days; only a current price may lead, be called the cheapest or lowest, be compared or enter a saving. `stale`: read longer ago. `undated`: WEM cannot say when. Those two read as "last seen £X on 8 Sep" or "price not dated", come after the current ones, and are not compared. Absent on a row a provider answered just now.'}, 'reviewCount': {'type': ['number', 'null']}, 'priceAgeDays': {'type': ['number', 'null'], 'description': 'Calendar days (UK time) since WEM last READ this price: 0 read today, 1 yesterday. Null means WEM cannot say. Null is undated, not current.'}, 'priceRefresh': {'enum': ['live-api', 'feed', 'none'], 'type': 'string', 'description': 'What re-reads this retailer’s prices: `live-api` a product-lookup API, `feed` a partner datafeed, `none` nothing on a schedule. `none` means the figure will not move on its own however long it sits ; `priceAgeDays` dates it.'}, 'priceQualifier': {'enum': ['from'], 'type': 'string', 'description': 'Present when `price` is the OPENING price of a range, not the price of this item: a multi-variation listing where the seller advertises its cheapest variant and the shopper picks a size on the page. It reads as "from £X"; it is not the item\'s price or the cheapest. Absent means the price is firm for the row as described.'}}}}, 'source': {'type': 'string'}, 'currency': {'type': ['string', 'null']}, 'identity': {'type': ['object', 'null'], 'properties': {'method': {'enum': ['gtin', 'slug', 'listing', 'title'], 'type': 'string'}, 'strength': {'enum': ['exact', 'catalogued', 'inferred'], 'type': 'string', 'description': 'exact = barcode; catalogued = a WEM key or listing id; inferred = matched on the product name, MPN or SKU and still a guess.'}}, 'description': 'How the shopper’s words reached this product. On `inferred`, WEM matched it by name (not by barcode) and the identity is not confirmed, even when `identityBasis` is `barcode`; on `exact`, the barcode itself resolved it.'}, 'lowPrice': {'type': ['number', 'null'], 'description': 'Lowest CURRENT price in `offers` (priceStatus `current`). Null when none is current: never fill it from an older or undated row.'}, 'unpriced': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link. The full URL; a shortened form is a different link.'}, 'title': {'type': 'string'}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string'}, 'provider': {'type': 'string'}, 'priceNote': {'type': 'string', 'description': 'What stands where a price would be, e.g. "See price at Amazon".'}}}, 'description': 'Listings whose price WEM may not show — today, Amazon rows Amazon’s API did not price just now. The row carries `priceNote` (e.g. "See price at Amazon") in place of a figure. No price is stated, estimated or compared for one; it is not the cheapest and is not counted in a lowest price or a saving.'}, 'productPage': {'type': 'string'}, 'identityBasis': {'enum': ['barcode', 'curated-grouping'], 'type': 'string', 'description': 'What this block’s identity rests on. `barcode` — the canonical product carries a GTIN and these offers are the same physical item. `curated-grouping` — it carries none, so the grouping is an inference of the same kind a title match is; do not describe it to the user as barcode-confirmed, and do not let it outrank a cheaper row in `products` on price alone. This is how the offers are grouped, not how the query matched the product — see `identity`.'}, 'lastConfirmedAt': {'type': ['string', 'null'], 'description': 'When WEM last actually read any price in this block. Null means none of them can be dated — say so rather than implying the block is current.'}, 'cheaperElsewhere': {'type': ['object', 'null'], 'properties': {'note': {'type': 'string', 'description': 'Plain-language restatement, safe to relay.'}, 'identity': {'enum': ['inferred'], 'type': 'string', 'description': 'Always `inferred` — matched on title, not barcode. Say so when quoting it.'}, 'verified': {'type': 'boolean', 'description': 'Always false.'}, 'savingVsCatalogue': {'type': 'number', 'description': 'How much cheaper this row is than the block’s lowest offer.'}}, 'description': 'Present only on a `curated-grouping` block that a live row in `products` undercuts. WEM is telling you its own catalogue block is not the best price it found. Quote this row as the cheaper option with its identity stated as unconfirmed; never present the catalogMatch price as the lowest when this is set.'}}, 'description': 'Offers WEM holds under one catalogue product. Check `identityBasis`: on `barcode` the product carries a GTIN and every offer here is that same item, so prefer them and cite their prices over anything in `products`. On `curated-grouping` the product carries no barcode, the grouping is an inference like any title match, and a cheaper row in `products` may well be the same item — see `cheaperElsewhere`. Whether the shopper’s words reached this product by barcode or by name is `identity`, a separate question: on `inferred`, say WEM matched it by name.'}, 'totalResults': {'type': 'number', 'description': 'Count of products returned, after weak matches were withheld.'}, 'catalogMatches': {'type': 'array', 'items': {'type': ['object', 'null'], 'properties': {'slug': {'type': 'string'}, 'title': {'type': 'string'}, 'offers': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link to the retailer page for this offer. WEM never takes payment.'}, 'brand': {'type': ['string', 'null']}, 'image': {'type': ['string', 'null']}, 'price': {'type': ['number', 'null'], 'description': 'Indicative price. The retailer sets the final price at checkout. Null, with `priceNote`, when WEM may not show this listing’s price: the note stands in place of a figure.'}, 'title': {'type': 'string'}, 'rating': {'type': ['number', 'null']}, 'seller': {'type': ['string', 'null']}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string', 'description': 'retailer is a named shop (Boots, Currys). marketplace is eBay/AliExpress/Temu-style parallel listings. A marketplace cluster is not a set of competing authorised retailers.'}, 'inStock': {'type': ['boolean', 'null']}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}, 'provider': {'type': 'string', 'description': 'Retailer slug, e.g. "ebay", "currys".'}, 'shipping': {'type': ['object', 'null'], 'properties': {'cost': {'type': ['number', 'null']}, 'free': {'type': 'boolean'}, 'estimate': {'type': ['string', 'null'], 'description': 'Delivery window when the feed stated one.'}}}, 'verified': {'type': 'boolean', 'description': 'True when WEM has recently observed this price on the retailer’s own surface. False means the identity is still catalogue-resolved but the price is indicative (partner feed or stale) — do not present it as verified.'}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'priceNote': {'type': 'string', 'description': 'Present only when `price` is null: the words that stand in its place, e.g. "See price at Amazon". An Amazon price is shown only when Amazon’s API supplied it just now.'}, 'unitPrice': {'type': 'object', 'properties': {'per': {'enum': ['100ml', 'litre', '100g', 'kg', 'item'], 'type': 'string'}, 'amount': {'type': 'number'}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}}, 'description': 'Price per 100ml, 100g, litre, kg or item, from the size this row\'s title states. Present only when the rows differ in size, in one unit across all of them, and only for things bought by the amount (beauty, food, supplements), never an appliance\'s capacity. Across sizes, value is compared on these, not on the prices: a smaller size is not cheaper because its price is lower. It reads beside the price ("£29.95, £99.83 per 100ml"). Absent does not mean the price is per unit.'}, 'lastSeenAt': {'type': ['string', 'null'], 'description': 'When WEM last READ this price from the retailer or a datafeed — the same reading `priceAgeDays` counts from, so the two always agree. Null means WEM cannot date the price: it is undated, not current.'}, 'priceStatus': {'enum': ['current', 'stale', 'undated'], 'type': 'string', 'description': '`current`: WEM read this price within the last 14 days; only a current price may lead, be called the cheapest or lowest, be compared or enter a saving. `stale`: read longer ago. `undated`: WEM cannot say when. Those two read as "last seen £X on 8 Sep" or "price not dated", come after the current ones, and are not compared. Absent on a row a provider answered just now.'}, 'reviewCount': {'type': ['number', 'null']}, 'priceAgeDays': {'type': ['number', 'null'], 'description': 'Calendar days (UK time) since WEM last READ this price: 0 read today, 1 yesterday. Null means WEM cannot say. Null is undated, not current.'}, 'priceRefresh': {'enum': ['live-api', 'feed', 'none'], 'type': 'string', 'description': 'What re-reads this retailer’s prices: `live-api` a product-lookup API, `feed` a partner datafeed, `none` nothing on a schedule. `none` means the figure will not move on its own however long it sits ; `priceAgeDays` dates it.'}, 'priceQualifier': {'enum': ['from'], 'type': 'string', 'description': 'Present when `price` is the OPENING price of a range, not the price of this item: a multi-variation listing where the seller advertises its cheapest variant and the shopper picks a size on the page. It reads as "from £X"; it is not the item\'s price or the cheapest. Absent means the price is firm for the row as described.'}}}}, 'source': {'type': 'string'}, 'currency': {'type': ['string', 'null']}, 'identity': {'type': ['object', 'null'], 'properties': {'method': {'enum': ['gtin', 'slug', 'listing', 'title'], 'type': 'string'}, 'strength': {'enum': ['exact', 'catalogued', 'inferred'], 'type': 'string', 'description': 'exact = barcode; catalogued = a WEM key or listing id; inferred = matched on the product name, MPN or SKU and still a guess.'}}, 'description': 'How the shopper’s words reached this product. On `inferred`, WEM matched it by name (not by barcode) and the identity is not confirmed, even when `identityBasis` is `barcode`; on `exact`, the barcode itself resolved it.'}, 'lowPrice': {'type': ['number', 'null'], 'description': 'Lowest CURRENT price in `offers` (priceStatus `current`). Null when none is current: never fill it from an older or undated row.'}, 'unpriced': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link. The full URL; a shortened form is a different link.'}, 'title': {'type': 'string'}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string'}, 'provider': {'type': 'string'}, 'priceNote': {'type': 'string', 'description': 'What stands where a price would be, e.g. "See price at Amazon".'}}}, 'description': 'Listings whose price WEM may not show — today, Amazon rows Amazon’s API did not price just now. The row carries `priceNote` (e.g. "See price at Amazon") in place of a figure. No price is stated, estimated or compared for one; it is not the cheapest and is not counted in a lowest price or a saving.'}, 'productPage': {'type': 'string'}, 'identityBasis': {'enum': ['barcode', 'curated-grouping'], 'type': 'string', 'description': 'What this block’s identity rests on. `barcode` — the canonical product carries a GTIN and these offers are the same physical item. `curated-grouping` — it carries none, so the grouping is an inference of the same kind a title match is; do not describe it to the user as barcode-confirmed, and do not let it outrank a cheaper row in `products` on price alone. This is how the offers are grouped, not how the query matched the product — see `identity`.'}, 'lastConfirmedAt': {'type': ['string', 'null'], 'description': 'When WEM last actually read any price in this block. Null means none of them can be dated — say so rather than implying the block is current.'}, 'cheaperElsewhere': {'type': ['object', 'null'], 'properties': {'note': {'type': 'string', 'description': 'Plain-language restatement, safe to relay.'}, 'identity': {'enum': ['inferred'], 'type': 'string', 'description': 'Always `inferred` — matched on title, not barcode. Say so when quoting it.'}, 'verified': {'type': 'boolean', 'description': 'Always false.'}, 'savingVsCatalogue': {'type': 'number', 'description': 'How much cheaper this row is than the block’s lowest offer.'}}, 'description': 'Present only on a `curated-grouping` block that a live row in `products` undercuts. WEM is telling you its own catalogue block is not the best price it found. Quote this row as the cheaper option with its identity stated as unconfirmed; never present the catalogMatch price as the lowest when this is set.'}}, 'description': 'Offers WEM holds under one catalogue product. Check `identityBasis`: on `barcode` the product carries a GTIN and every offer here is that same item, so prefer them and cite their prices over anything in `products`. On `curated-grouping` the product carries no barcode, the grouping is an inference like any title match, and a cheaper row in `products` may well be the same item — see `cheaperElsewhere`. Whether the shopper’s words reached this product by barcode or by name is `identity`, a separate question: on `inferred`, say WEM matched it by name.'}, 'description': 'Present when the query was a comma-separated batch of identifiers and more than one catalogue product resolved. Each entry has the same shape as `catalogMatch`. Prefer barcode-basis blocks; treat MPN/SKU/title blocks as inferred.'}, 'pending_providers': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Providers still running when the budget expired. Present only with partial.'}}}
search_promotions
Find current retailer promotions
Lists current promotions (sales and offers) that retailers in WEM's Awin affiliate programmes have published, for the shopper's market. Filter by merchant or by words in the offer. Each row gives the offer, its dates and a tracked link. A promotion is not a price, and it is not a discount on a product unless its terms say it covers that product. Checkout codes are shown only where the retailer's programme lets WEM publish them; other matching promotions are counted by reason in `withheld`, and a withheld code may still exist. An empty result covers only these programmes, not every offer a retailer runs.
Lecture seule Accès externe
Schéma d’entrée
{'type': 'object', 'properties': {'limit': {'type': 'number', 'description': 'Max promotions to return (default 10, max 25).'}, 'query': {'type': 'string', 'description': 'Words that must appear in the offer, e.g. "hoverboard" or "free delivery".'}, 'currency': {'type': 'string', 'description': "ISO 4217 code for the shopper's market: GBP (default) or USD. Promotions are regional, so this decides which market's offers are read."}, 'merchant': {'type': 'string', 'description': 'Retailer name, e.g. "iHoverboard". Omit for every retailer.'}}}
Schéma de sortie
{'type': 'object', 'required': ['promotions', 'count', 'currency', 'links', 'disclosure'], 'properties': {'more': {'type': 'number', 'description': 'Further matching promotions beyond `limit`.'}, 'note': {'type': 'string'}, 'count': {'type': 'number'}, 'links': {'type': 'array', 'items': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'title': {'type': 'string'}, 'markdown': {'type': 'string'}, 'merchant': {'type': 'string'}}}, 'description': 'The tracked links from `promotions`, pre-formatted. Give these to the user when you name a promotion.'}, 'market': {'type': 'string', 'description': 'ISO country code the promotions were read for.'}, 'reason': {'enum': ['none_matched', 'not_configured', 'upstream_error', 'unsupported_market'], 'type': 'string', 'description': 'Present only when no promotion is shown. None of these means the retailer has no offer on — not_configured and upstream_error mean WEM could not look.'}, 'search': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'reason': {'type': 'string'}, 'markdown': {'type': 'string', 'description': 'The same link, pre-formatted.'}}, 'description': "Present when this result names no offer. `url` is WEM's results page for the query and `markdown` is the same link, pre-formatted. WEM searches retailers live on that page, including shops it holds no affiliate programme with, so an empty or withheld result here is not evidence the product is unavailable or unpriced."}, 'currency': {'type': 'string'}, 'withheld': {'type': 'object', 'description': 'Matching promotions WEM did not show, counted by reason: notPublishable (a checkout code or offer the retailer’s programme does not let WEM publish; the code may well exist), notJoined, notActive, outsideMarket, noTrackedLink, otherPublisherLink, incompleteRecord.', 'additionalProperties': {'type': 'number'}}, 'disclosure': {'type': 'string', 'description': 'WEM’s affiliate disclosure for this answer, written to be quoted as it is. Its wording changes with the rows: it states whether every outbound link is affiliate-tracked, only some are, or none are. A version from an earlier answer may not fit this one: a row marked `affiliate: false` earns WEM nothing.'}, 'promotions': {'type': 'array', 'items': {'type': 'object', 'required': ['merchant', 'title', 'kind', 'url'], 'properties': {'url': {'type': 'string', 'description': 'WEM tracked redirect to the retailer’s promotion page. The full URL; a shortened or rewritten form is a different link.'}, 'code': {'type': 'string'}, 'kind': {'enum': ['sale', 'code'], 'type': 'string', 'description': 'code rows carry `code`, and appear only where the retailer’s programme lets WEM publish it.'}, 'terms': {'type': 'string', 'description': 'The retailer’s own conditions. Relay them with the offer.'}, 'title': {'type': 'string'}, 'endsAt': {'type': ['string', 'null'], 'description': 'When the retailer said it ends. Null means no end was stated — do not invent one.'}, 'network': {'type': 'string'}, 'merchant': {'type': 'string'}, 'startsAt': {'type': ['string', 'null']}, 'description': {'type': 'string'}}}, 'description': 'Ending soonest first. Each row is one live promotion WEM is allowed to show.'}, 'withheldNote': {'type': 'string', 'description': 'Quote this rather than paraphrase it when codes were withheld.'}}, 'description': 'Promotions the retailer published to its affiliate network, filtered by WEM’s programme terms. A promotion is the retailer’s claim about some of its range, not a price — never compute a discounted price from it unless its terms name the product.'}
semantic_search
Find products by description
Searches WEM's partner-feed products by meaning, for a plain-language need such as "comfortable shoes for standing all day" or "gift for a 10 year old who likes science". If the description is a product identifier (a barcode, ASIN, MPN, merchant SKU or wem3.ai/pl URL), that product is looked up instead and the reply takes the keyword-search shape. When no products come back, `reason` says why: `index_empty` means nothing matched; `no_embedding_key`, `no_catalogue_client`, `embedding_failed`, `query_failed` and `timed_out` mean the semantic index could not be searched this time, which says nothing about whether such products exist.
Lecture seule Accès externe
Schéma d’entrée
{'type': 'object', 'required': ['description'], 'properties': {'limit': {'type': 'number', 'description': 'Max products to return (default 10, max 20).'}, 'category': {'type': 'string', 'description': 'Optional. Keeps only products whose feed category matches this text exactly.'}, 'provider': {'type': 'string', 'description': 'Optional. Keeps only products from this partner feed, e.g. "awin".'}, 'max_price': {'type': 'number', 'description': "Optional upper price bound, compared with each product's listed price (currencies are not converted)."}, 'min_price': {'type': 'number', 'description': "Optional lower price bound, compared with each product's listed price (currencies are not converted)."}, 'description': {'type': 'string', 'description': 'Plain-language description of what the shopper needs.'}}}
Schéma de sortie
{'type': 'object', 'required': ['products', 'totalResults', 'disclosure'], 'properties': {'next': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'reason': {'type': 'string'}, 'surface': {'enum': ['chrome_extension'], 'type': 'string'}}, 'description': "Present when WEM's set of offers is thin. chrome_extension is a page that compares the same product on any retailer page, including shops without an affiliate programme."}, 'query': {'type': 'string'}, 'reason': {'type': 'string', 'description': 'Present when semantic is false, and never a judgement on the shopper query. `index_empty` — the vector query ran and matched nothing. `no_catalogue_client` / `no_embedding_key` — WEM is misconfigured, not the catalogue empty. `embedding_failed` / `query_failed` — an upstream call failed; retrying later may succeed. `timed_out` — an upstream call did not answer in time; this says nothing about the catalogue.'}, 'search': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'reason': {'type': 'string'}, 'markdown': {'type': 'string', 'description': 'The same link, pre-formatted.'}}, 'description': "Present when this result names no offer. `url` is WEM's results page for the query and `markdown` is the same link, pre-formatted. WEM searches retailers live on that page, including shops it holds no affiliate programme with, so an empty or withheld result here is not evidence the product is unavailable or unpriced."}, 'filtered': {'type': ['object', 'null'], 'description': 'Withheld candidates tallied by reason (e.g. accessories, another model, a bundle or multipack, a replica, a listing priced far below the product’s other offers). Report this count rather than implying the search was exhaustive, and never quote a withheld listing’s price as the cheapest or as a deal.', 'additionalProperties': {'type': 'number'}}, 'products': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link to the retailer page for this offer. WEM never takes payment.'}, 'brand': {'type': ['string', 'null']}, 'image': {'type': ['string', 'null']}, 'price': {'type': ['number', 'null'], 'description': 'Indicative price. The retailer sets the final price at checkout. Null, with `priceNote`, when WEM may not show this listing’s price: the note stands in place of a figure.'}, 'title': {'type': 'string'}, 'rating': {'type': ['number', 'null']}, 'seller': {'type': ['string', 'null']}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string', 'description': 'retailer is a named shop (Boots, Currys). marketplace is eBay/AliExpress/Temu-style parallel listings. A marketplace cluster is not a set of competing authorised retailers.'}, 'inStock': {'type': ['boolean', 'null']}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}, 'provider': {'type': 'string', 'description': 'Retailer slug, e.g. "ebay", "currys".'}, 'shipping': {'type': ['object', 'null'], 'properties': {'cost': {'type': ['number', 'null']}, 'free': {'type': 'boolean'}, 'estimate': {'type': ['string', 'null'], 'description': 'Delivery window when the feed stated one.'}}}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'priceNote': {'type': 'string', 'description': 'Present only when `price` is null: the words that stand in its place, e.g. "See price at Amazon". An Amazon price is shown only when Amazon’s API supplied it just now.'}, 'unitPrice': {'type': 'object', 'properties': {'per': {'enum': ['100ml', 'litre', '100g', 'kg', 'item'], 'type': 'string'}, 'amount': {'type': 'number'}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}}, 'description': 'Price per 100ml, 100g, litre, kg or item, from the size this row\'s title states. Present only when the rows differ in size, in one unit across all of them, and only for things bought by the amount (beauty, food, supplements), never an appliance\'s capacity. Across sizes, value is compared on these, not on the prices: a smaller size is not cheaper because its price is lower. It reads beside the price ("£29.95, £99.83 per 100ml"). Absent does not mean the price is per unit.'}, 'priceStatus': {'enum': ['current', 'stale', 'undated'], 'type': 'string', 'description': '`current`: WEM read this price within the last 14 days; only a current price may lead, be called the cheapest or lowest, be compared or enter a saving. `stale`: read longer ago. `undated`: WEM cannot say when. Those two read as "last seen £X on 8 Sep" or "price not dated", come after the current ones, and are not compared. Absent on a row a provider answered just now.'}, 'reviewCount': {'type': ['number', 'null']}, 'priceQualifier': {'enum': ['from'], 'type': 'string', 'description': 'Present when `price` is the OPENING price of a range, not the price of this item: a multi-variation listing where the seller advertises its cheapest variant and the shopper picks a size on the page. It reads as "from £X"; it is not the item\'s price or the cheapest. Absent means the price is firm for the row as described.'}}}}, 'semantic': {'type': 'boolean', 'description': 'True only when the vector path actually ran.'}, 'disclosure': {'type': 'string', 'description': 'WEM’s affiliate disclosure for this answer, written to be quoted as it is. Its wording changes with the rows: it states whether every outbound link is affiliate-tracked, only some are, or none are. A version from an earlier answer may not fit this one: a row marked `affiliate: false` earns WEM nothing.'}, 'catalogMatch': {'type': ['object', 'null'], 'properties': {'slug': {'type': 'string'}, 'title': {'type': 'string'}, 'offers': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link to the retailer page for this offer. WEM never takes payment.'}, 'brand': {'type': ['string', 'null']}, 'image': {'type': ['string', 'null']}, 'price': {'type': ['number', 'null'], 'description': 'Indicative price. The retailer sets the final price at checkout. Null, with `priceNote`, when WEM may not show this listing’s price: the note stands in place of a figure.'}, 'title': {'type': 'string'}, 'rating': {'type': ['number', 'null']}, 'seller': {'type': ['string', 'null']}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string', 'description': 'retailer is a named shop (Boots, Currys). marketplace is eBay/AliExpress/Temu-style parallel listings. A marketplace cluster is not a set of competing authorised retailers.'}, 'inStock': {'type': ['boolean', 'null']}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}, 'provider': {'type': 'string', 'description': 'Retailer slug, e.g. "ebay", "currys".'}, 'shipping': {'type': ['object', 'null'], 'properties': {'cost': {'type': ['number', 'null']}, 'free': {'type': 'boolean'}, 'estimate': {'type': ['string', 'null'], 'description': 'Delivery window when the feed stated one.'}}}, 'verified': {'type': 'boolean', 'description': 'True when WEM has recently observed this price on the retailer’s own surface. False means the identity is still catalogue-resolved but the price is indicative (partner feed or stale) — do not present it as verified.'}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'priceNote': {'type': 'string', 'description': 'Present only when `price` is null: the words that stand in its place, e.g. "See price at Amazon". An Amazon price is shown only when Amazon’s API supplied it just now.'}, 'unitPrice': {'type': 'object', 'properties': {'per': {'enum': ['100ml', 'litre', '100g', 'kg', 'item'], 'type': 'string'}, 'amount': {'type': 'number'}, 'currency': {'type': 'string', 'description': 'ISO 4217 code.'}}, 'description': 'Price per 100ml, 100g, litre, kg or item, from the size this row\'s title states. Present only when the rows differ in size, in one unit across all of them, and only for things bought by the amount (beauty, food, supplements), never an appliance\'s capacity. Across sizes, value is compared on these, not on the prices: a smaller size is not cheaper because its price is lower. It reads beside the price ("£29.95, £99.83 per 100ml"). Absent does not mean the price is per unit.'}, 'lastSeenAt': {'type': ['string', 'null'], 'description': 'When WEM last READ this price from the retailer or a datafeed — the same reading `priceAgeDays` counts from, so the two always agree. Null means WEM cannot date the price: it is undated, not current.'}, 'priceStatus': {'enum': ['current', 'stale', 'undated'], 'type': 'string', 'description': '`current`: WEM read this price within the last 14 days; only a current price may lead, be called the cheapest or lowest, be compared or enter a saving. `stale`: read longer ago. `undated`: WEM cannot say when. Those two read as "last seen £X on 8 Sep" or "price not dated", come after the current ones, and are not compared. Absent on a row a provider answered just now.'}, 'reviewCount': {'type': ['number', 'null']}, 'priceAgeDays': {'type': ['number', 'null'], 'description': 'Calendar days (UK time) since WEM last READ this price: 0 read today, 1 yesterday. Null means WEM cannot say. Null is undated, not current.'}, 'priceRefresh': {'enum': ['live-api', 'feed', 'none'], 'type': 'string', 'description': 'What re-reads this retailer’s prices: `live-api` a product-lookup API, `feed` a partner datafeed, `none` nothing on a schedule. `none` means the figure will not move on its own however long it sits ; `priceAgeDays` dates it.'}, 'priceQualifier': {'enum': ['from'], 'type': 'string', 'description': 'Present when `price` is the OPENING price of a range, not the price of this item: a multi-variation listing where the seller advertises its cheapest variant and the shopper picks a size on the page. It reads as "from £X"; it is not the item\'s price or the cheapest. Absent means the price is firm for the row as described.'}}}}, 'source': {'type': 'string'}, 'currency': {'type': ['string', 'null']}, 'identity': {'type': ['object', 'null'], 'properties': {'method': {'enum': ['gtin', 'slug', 'listing', 'title'], 'type': 'string'}, 'strength': {'enum': ['exact', 'catalogued', 'inferred'], 'type': 'string', 'description': 'exact = barcode; catalogued = a WEM key or listing id; inferred = matched on the product name, MPN or SKU and still a guess.'}}, 'description': 'How the shopper’s words reached this product. On `inferred`, WEM matched it by name (not by barcode) and the identity is not confirmed, even when `identityBasis` is `barcode`; on `exact`, the barcode itself resolved it.'}, 'lowPrice': {'type': ['number', 'null'], 'description': 'Lowest CURRENT price in `offers` (priceStatus `current`). Null when none is current: never fill it from an older or undated row.'}, 'unpriced': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string', 'description': 'WEM tracked link. The full URL; a shortened form is a different link.'}, 'title': {'type': 'string'}, 'channel': {'enum': ['retailer', 'marketplace'], 'type': 'string'}, 'provider': {'type': 'string'}, 'priceNote': {'type': 'string', 'description': 'What stands where a price would be, e.g. "See price at Amazon".'}}}, 'description': 'Listings whose price WEM may not show — today, Amazon rows Amazon’s API did not price just now. The row carries `priceNote` (e.g. "See price at Amazon") in place of a figure. No price is stated, estimated or compared for one; it is not the cheapest and is not counted in a lowest price or a saving.'}, 'productPage': {'type': 'string'}, 'identityBasis': {'enum': ['barcode', 'curated-grouping'], 'type': 'string', 'description': 'What this block’s identity rests on. `barcode` — the canonical product carries a GTIN and these offers are the same physical item. `curated-grouping` — it carries none, so the grouping is an inference of the same kind a title match is; do not describe it to the user as barcode-confirmed, and do not let it outrank a cheaper row in `products` on price alone. This is how the offers are grouped, not how the query matched the product — see `identity`.'}, 'lastConfirmedAt': {'type': ['string', 'null'], 'description': 'When WEM last actually read any price in this block. Null means none of them can be dated — say so rather than implying the block is current.'}, 'cheaperElsewhere': {'type': ['object', 'null'], 'properties': {'note': {'type': 'string', 'description': 'Plain-language restatement, safe to relay.'}, 'identity': {'enum': ['inferred'], 'type': 'string', 'description': 'Always `inferred` — matched on title, not barcode. Say so when quoting it.'}, 'verified': {'type': 'boolean', 'description': 'Always false.'}, 'savingVsCatalogue': {'type': 'number', 'description': 'How much cheaper this row is than the block’s lowest offer.'}}, 'description': 'Present only on a `curated-grouping` block that a live row in `products` undercuts. WEM is telling you its own catalogue block is not the best price it found. Quote this row as the cheaper option with its identity stated as unconfirmed; never present the catalogMatch price as the lowest when this is set.'}}, 'description': 'Offers WEM holds under one catalogue product. Check `identityBasis`: on `barcode` the product carries a GTIN and every offer here is that same item, so prefer them and cite their prices over anything in `products`. On `curated-grouping` the product carries no barcode, the grouping is an inference like any title match, and a cheaper row in `products` may well be the same item — see `cheaperElsewhere`. Whether the shopper’s words reached this product by barcode or by name is `identity`, a separate question: on `inferred`, say WEM matched it by name.'}, 'totalResults': {'type': 'number'}}, 'description': 'Empty when the vector path cannot rank (`semantic: false`), with `reason` naming which cause applies — they have different fixes, so do not read them all as an empty index. `semantic` is true only when pgvector actually ranked products.'}
verify_offer
Check whether a price claim is true
Checks a price someone has claimed for a product against the prices WEM has itself observed at retailers (recent readings, within a small tolerance; not a live quote), and reports the cheapest observed offer. Identify the product by gtin (strongest), slug, wem_id, provider + externalId, or title (weakest, relevance-checked). `retailer` names the shop the claim is about; without it the nearest observed price at any shop is checked. Only offers in the claim's currency are compared. Verdicts: confirmed (WEM observed that price there), price_moved (WEM last observed a different price there), not_at_retailer (WEM has no observed price there, though it may hold a feed price), no_claim (no price given; the offers are returned), unknown_product (the product could not be resolved, or WEM holds no observed price for it in that currency). unknown_product means the claim could not be checked, not that it is false. `lastConfirmedAt` says when WEM last observed a price in the answer, or is null. Each call records an evidence receipt, whose id can be cited later.
Schéma d’entrée
{'type': 'object', 'anyOf': [{'required': ['gtin']}, {'required': ['slug']}, {'required': ['wem_id']}, {'required': ['provider', 'externalId']}, {'required': ['title']}], 'properties': {'gtin': {'type': 'string', 'description': 'Product barcode: EAN-13, UPC-A, EAN-8 or GTIN-14. Strongest identifier.'}, 'slug': {'type': 'string', 'description': 'WEM canonical slug, as in wem3.ai/pl/{slug}.'}, 'price': {'type': 'number', 'description': 'The price being claimed. Omit to ask only for the observed offers.'}, 'title': {'type': 'string', 'description': 'Product title. The weakest identifier: used only when no id is given, and only if it passes a relevance check.'}, 'wem_id': {'type': 'string', 'description': 'WEM ID (W + 10 Crockford characters + check). Active catalogue products only.'}, 'currency': {'type': 'string', 'description': 'ISO 4217 code for the claimed price. Default GBP. Only offers in this currency are compared.'}, 'provider': {'type': 'string', 'description': "With externalId: the retailer source of a listing that identifies the product, e.g. 'amazon' or 'ebay'. To name the shop the claim is about, use `retailer`."}, 'retailer': {'type': 'string', 'description': 'The shop the price was claimed at, as a slug or display name. Omit to compare against every shop.'}, 'externalId': {'type': 'string', 'description': "That listing's own id (ASIN, eBay item number). Use with provider."}}}
Schéma de sortie
{'type': 'object', 'required': ['verdict', 'offers', 'summary', 'source', 'disclosure', 'receipt'], 'properties': {'offers': {'type': 'array', 'items': {'type': ['object', 'null'], 'properties': {'url': {'type': 'string'}, 'price': {'type': 'number'}, 'inStock': {'type': ['boolean', 'null'], 'description': 'null means the retailer did not report availability. Say "stock not confirmed" — never present null as in stock.'}, 'currency': {'type': 'string'}, 'provider': {'type': 'string'}, 'retailer': {'type': 'string', 'description': 'Shopper-facing retailer name.'}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'totalCost': {'type': 'object', 'properties': {'tax': {'type': ['number', 'null']}, 'fees': {'type': ['number', 'null']}, 'item': {'type': 'number'}, 'unknown': {'type': 'array', 'items': {'type': 'string'}}, 'currency': {'type': 'string'}, 'shipping': {'type': ['number', 'null']}, 'delivered': {'type': 'number'}, 'confidence': {'enum': ['stated', 'unknown'], 'type': 'string'}}, 'description': 'Item plus any stated extras. When unknown is non-empty, delivered is a floor — never relay it as what the shopper will pay.'}}}, 'description': 'Prices WEM holds for this product, including indicative ones and shops it has no affiliate programme with yet. When `cheapest` is null, still show these rows and their links: they are a comparison, not a verification. Do not call them confirmed, and do not name a verified cheapest.'}, 'source': {'type': 'string'}, 'product': {'type': ['object', 'null'], 'properties': {'slug': {'type': 'string'}, 'title': {'type': 'string'}}}, 'receipt': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'amount': {'type': ['number', 'null'], 'description': 'Major-unit decimal, same units as verify_offer prices.'}, 'signed': {'type': 'boolean', 'description': 'True when WEM signed this receipt with a dedicated HMAC key. False when no key is configured (fail closed). Never derived from CRON_SECRET.'}, 'source': {'type': 'string', 'description': 'Citable URI of the standard this receipt is issued under.'}, 'verdict': {'type': 'string'}, 'currency': {'type': ['string', 'null']}, 'issuedAt': {'type': 'string', 'description': 'Alias of observed_at, kept for the unsigned edition.'}, 'verifier': {'type': 'string', 'description': 'Always "wem".'}, 'signature': {'type': ['string', 'null'], 'description': 'hmac-sha256=<hex> when signed; otherwise null.'}, 'observed_at': {'type': 'string', 'description': 'When WEM read the price in amount, or "unobserved" when nothing dates it — then do not present amount as current. ACP #197.'}, 'amount_minor': {'type': ['number', 'null'], 'description': 'Integer minor units of amount, ACP form.'}, 'identity_method': {'type': ['string', 'null']}, 'standardVersion': {'type': 'string'}}, 'description': 'Citation handle for this answer. Field names follow ACP suggested_price (observed_at, source, amount). signed is true only when WEM issued an HMAC with a dedicated key; otherwise false (fail closed).'}, 'summary': {'type': 'string', 'description': 'Written so quoting it verbatim is accurate. Prefer quoting it to paraphrasing the verdict code.'}, 'verdict': {'enum': ['confirmed', 'price_moved', 'not_at_retailer', 'no_claim', 'unknown_product'], 'type': 'string'}, 'betterBy': {'type': ['number', 'null'], 'description': 'Saving from taking `cheapest` over the claimed price. Never negative.'}, 'cheapest': {'type': ['object', 'null'], 'properties': {'url': {'type': 'string'}, 'price': {'type': 'number'}, 'inStock': {'type': ['boolean', 'null'], 'description': 'null means the retailer did not report availability. Say "stock not confirmed" — never present null as in stock.'}, 'currency': {'type': 'string'}, 'provider': {'type': 'string'}, 'retailer': {'type': 'string', 'description': 'Shopper-facing retailer name.'}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'totalCost': {'type': 'object', 'properties': {'tax': {'type': ['number', 'null']}, 'fees': {'type': ['number', 'null']}, 'item': {'type': 'number'}, 'unknown': {'type': 'array', 'items': {'type': 'string'}}, 'currency': {'type': 'string'}, 'shipping': {'type': ['number', 'null']}, 'delivered': {'type': 'number'}, 'confidence': {'enum': ['stated', 'unknown'], 'type': 'string'}}, 'description': 'Item plus any stated extras. When unknown is non-empty, delivered is a floor — never relay it as what the shopper will pay.'}}}, 'identity': {'type': ['object', 'null'], 'properties': {'method': {'enum': ['gtin', 'slug', 'listing', 'title'], 'type': 'string'}, 'strength': {'enum': ['exact', 'catalogued', 'inferred'], 'type': 'string', 'description': 'exact = barcode; catalogued = a WEM key or the retailer’s own listing id; inferred = matched on the product name and still a guess.'}}, 'description': 'How the product was identified — a separate question from whether the price checks out. Never present a `strength` of "inferred" as a verified identity.'}, 'sameModel': {'type': 'array', 'items': {'type': 'object', 'required': ['model', 'relation', 'differences', 'maker', 'checkedOn', 'summary'], 'properties': {'url': {'type': ['string', 'null'], 'description': "WEM's comparison for that model, not a shop."}, 'maker': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'host': {'type': 'string'}, 'says': {'type': 'string', 'description': "The page's words, as checked."}}, 'description': "The maker's own page that says so: the proof. WEM is not the source of the claim."}, 'model': {'type': 'string', 'description': 'The other model code, as the maker writes it.'}, 'summary': {'type': 'string', 'description': 'WEM’s words for it, written to be quoted as they are.'}, 'cheapest': {'type': ['object', 'null'], 'properties': {'shop': {'type': 'string'}, 'price': {'type': 'number'}, 'currency': {'type': 'string'}, 'priceAgeDays': {'type': ['number', 'null'], 'description': 'Days since WEM read that price. Null means undated.'}}, 'description': "The other model's cheapest named shop. Null when no named shop has an in-stock price for it. `priceAgeDays` gives its age; without one it is not current."}, 'relation': {'enum': ['identical', 'differs'], 'type': 'string', 'description': '`identical`: the maker says it is the same product. `differs`: the same product except `differences`; not like for like.'}, 'checkedOn': {'type': 'string', 'description': 'When a person at WEM read the maker’s page (YYYY-MM-DD).'}, 'differences': {'type': 'array', 'items': {'type': 'string'}, 'description': 'What the maker says differs. Empty when identical.'}}}, 'description': "Present only when the maker's own page says another model code is this product and a person at WEM has checked it. These are NOT offers for the product asked about: they are not part of `offers`, and none is this product's lowest price or the best deal. On verify_offer they are not part of the check: `verdict`, `cheapest`, `betterBy`, `summary` and the receipt are about the product asked about, and a cheaper sister code never makes the claimed price wrong. `summary` is written to be quoted as it is. `maker.host` is the source of the claim. `url` is WEM's comparison for that model, not a shop. When `relation` is `differs`, the `differences` are what the maker says differs, and its price is not a saving. Absent is not evidence that no equivalent exists."}, 'disclosure': {'type': 'string', 'description': 'WEM’s affiliate disclosure for this answer, written to be quoted as it is. Its wording changes with the rows: it states whether every outbound link is affiliate-tracked, only some are, or none are. A version from an earlier answer may not fit this one: a row marked `affiliate: false` earns WEM nothing.'}, 'resolvedBy': {'type': ['string', 'null'], 'description': 'Which identifier resolved the product.'}, 'claimMatched': {'type': ['object', 'null'], 'properties': {'url': {'type': 'string'}, 'price': {'type': 'number'}, 'inStock': {'type': ['boolean', 'null'], 'description': 'null means the retailer did not report availability. Say "stock not confirmed" — never present null as in stock.'}, 'currency': {'type': 'string'}, 'provider': {'type': 'string'}, 'retailer': {'type': 'string', 'description': 'Shopper-facing retailer name.'}, 'affiliate': {'type': 'boolean', 'description': 'False when this link earns WEM nothing: the shop has no affiliate programme with WEM, or this link does not carry one. It is still a real offer, and its link is not affiliate-tracked. Absent (or true) means the link is affiliate-tracked. `disclosure` states whether all, some or none of the links are tracked.'}, 'totalCost': {'type': 'object', 'properties': {'tax': {'type': ['number', 'null']}, 'fees': {'type': ['number', 'null']}, 'item': {'type': 'number'}, 'unknown': {'type': 'array', 'items': {'type': 'string'}}, 'currency': {'type': 'string'}, 'shipping': {'type': ['number', 'null']}, 'delivered': {'type': 'number'}, 'confidence': {'enum': ['stated', 'unknown'], 'type': 'string'}}, 'description': 'Item plus any stated extras. When unknown is non-empty, delivered is a floor — never relay it as what the shopper will pay.'}}}, 'comparisonSet': {'type': ['object', 'null'], 'properties': {'exhaustive': {'type': 'boolean', 'description': 'Always false. Never present this answer as the lowest price available anywhere.'}, 'observedAt': {'type': ['string', 'null']}, 'offersCompared': {'type': 'number'}, 'retailersCompared': {'type': 'number'}}, 'description': 'How wide the comparison behind `cheapest` was. `exhaustive` is always false: WEM does not see every retailer, so `cheapest` is the lowest offer WEM holds, never the lowest that exists. Relay it as such.'}, 'lastConfirmedAt': {'type': ['string', 'null'], 'description': 'When WEM last read a price among the offers compared — the freshness of this answer. Null means none of them carries a dated reading: say the prices are undated.'}, 'toleranceApplied': {'type': ['number', 'null']}}, 'description': '`unknown_product` means the claim could NOT be checked. It never means the claim is false and must not be reported as one.'}
Modifié
search_promotions
5 October 2026 02:52
Modifié
get_evidence_receipt
5 October 2026 02:52
Modifié
lookup_products
5 October 2026 02:52
Modifié
verify_offer
5 October 2026 02:52
Modifié
compare_offers
5 October 2026 02:52
Modifié
find_lowest_price
5 October 2026 02:52
Modifié
compare_products
5 October 2026 02:52
Modifié
get_product
5 October 2026 02:52
Modifié
get_categories
5 October 2026 02:52
Modifié
semantic_search
5 October 2026 02:52
Modifié
search_products
5 October 2026 02:52
Modifié
verify_offer
3 October 2026 02:59
Modifié
compare_offers
3 October 2026 02:59
Modifié
find_lowest_price
3 October 2026 02:59
Modifié
semantic_search
3 October 2026 02:59
Modifié
search_products
3 October 2026 02:59
Modifié
compare_offers
1 October 2026 02:52
Modifié
find_lowest_price
1 October 2026 02:52
Modifié
compare_products
1 October 2026 02:52
Modifié
get_product
1 October 2026 02:52
Modifié
semantic_search
1 October 2026 02:52
Modifié
search_products
1 October 2026 02:52
Modifié
compare_offers
29 September 2026 03:00
Modifié
find_lowest_price
29 September 2026 03:00
Modifié
semantic_search
29 September 2026 03:00
Modifié
search_products
29 September 2026 03:00
Ajouté
search_promotions
25 September 2026 03:00
Modifié
get_evidence_receipt
25 September 2026 03:00
Ajouté
lookup_products
25 September 2026 03:00
Modifié
verify_offer
25 September 2026 03:00