{"openapi":"3.1.0","info":{"title":"Findcheap API","description":"Where the product on a page is sold for less. Read a product page, search the marketplaces of a market for the same product and for acceptable equivalents, resolve a card's link, give feedback on a search. Keys and credits: https://findcheap.ai/developers. The reference: https://findcheap.ai/developers/docs. For agents: https://findcheap.ai/llms.txt. The same calls are MCP tools at https://mcp.findcheap.ai/mcp.","version":"1"},"servers":[{"url":"https://api.findcheap.ai"}],"paths":{"/v1/search":{"post":{"summary":"Find the product on a page sold for less","description":"Read the product page, then search the marketplaces of the shopper's market for the same product\nand for acceptable equivalents, cheapest first. Answers within 60 seconds; most searches take 15 to 30.","operationId":"search","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchIn"}}}},"responses":{"200":{"description":"What was searched, the page as read, the same product elsewhere, acceptable equivalents. 10 credits.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Search","$ref":"#/components/schemas/SearchAnswer"}}}},"400":{"description":"invalid_request (a malformed body), invalid_url or unknown_market.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"unauthorized: no key, or a key that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"credits_exhausted: the account has used its plan's credits for the period.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"account_suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"not_searchable (the address is not a readable product page) or refused (a used search on grocery or consumable products, or with no determinable brand). Billed as a page read, 1 credit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"rate_limited: over a per-minute limit; Retry-After says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"search_failed: something failed on our side; safe to retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"unreachable: the page could not be fetched right now; a retry later may succeed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"account_service_unavailable: the key could not be checked right now; safe to retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"504":{"description":"timeout: the call ran past its time limit (30 seconds for a read, 60 for a search); safe to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/resolve":{"post":{"summary":"Resolve a card's link","description":"The merchant's link for a search card that came with a resolve_id instead of a url. An id is valid for\nabout two hours after its search.","operationId":"resolve","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveIn"}}}},"responses":{"200":{"description":"The merchant's link and name. 1 credit when a link came back, 0 otherwise.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Resolve","$ref":"#/components/schemas/ResolveAnswer"}}}},"400":{"description":"invalid_request (a malformed body), invalid_url or unknown_market.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"unauthorized: no key, or a key that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"credits_exhausted: the account has used its plan's credits for the period.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"account_suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"rate_limited: over a per-minute limit; Retry-After says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"search_failed: something failed on our side; safe to retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"account_service_unavailable: the key could not be checked right now; safe to retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/extract":{"post":{"summary":"Read a product page","description":"Read a product page and answer what it sells, without searching: title, image, price, currency,\nbrand, in_stock. Answers within 30 seconds.","operationId":"extract","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractIn"}}}},"responses":{"200":{"description":"The page as read. 1 credit.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Extract","$ref":"#/components/schemas/ReadAnswer"}}}},"400":{"description":"invalid_request (a malformed body), invalid_url or unknown_market.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"unauthorized: no key, or a key that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"credits_exhausted: the account has used its plan's credits for the period.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"account_suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"rate_limited: over a per-minute limit; Retry-After says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"unreachable: the page could not be fetched right now; a retry later may succeed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"account_service_unavailable: the key could not be checked right now; safe to retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"504":{"description":"timeout: the call ran past its time limit (30 seconds for a read, 60 for a search); safe to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/search/{request_id}/feedback":{"post":{"summary":"Give feedback on a search","description":"Report how a search went, by the search's `request_id`: which cards were useful, which do not belong in\ntheir list, a cheaper listing found elsewhere, what was missing. One report per search, within 20 minutes\nof it. The first report on a search gives 1 credit back, up to 100 credits a day.","operationId":"search_feedback","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackIn"}}}},"responses":{"200":{"description":"Whether the report was recorded and the credit it gave back. Costs nothing.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Search Feedback","$ref":"#/components/schemas/FeedbackAnswer"}}}},"400":{"description":"invalid_request (a malformed body), invalid_url or unknown_market.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"unauthorized: no key, or a key that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"rate_limited: over a per-minute limit; Retry-After says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"account_service_unavailable: the key could not be checked right now; safe to retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"account_suspended, or feedback_off: feedback is switched off for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"search_not_found: no search with this id was made by this account in the last 20 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}}},"components":{"schemas":{"Card":{"properties":{"title":{"type":"string","title":"Title","description":"The listing's title, as the retailer shows it."},"price":{"type":"number","title":"Price","description":"The live, buyable price of the item alone, without shipping, in `currency`. When `coupon` is set, this is the price after the coupon or code."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"The ISO 4217 code of `price` (USD, CAD, AUD, INR). Null means the market's currency."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The listing's link. Null when the link must be fetched first with `resolve_id` (resolve_listing on the MCP server, POST /v1/resolve on the API). On the Free plan it may be an affiliate link."},"image":{"type":"string","title":"Image","description":"The listing's photo."},"retailer":{"type":"string","title":"Retailer","description":"Where the product is sold: Amazon, Walmart, eBay, AliExpress, Shein, Flipkart, or the store's name for a listing found across the web."},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating","description":"The retailer's rating: stars out of 5 on most retailers; on eBay the seller's positive-feedback percentage (0 to 100). Null when unknown."},"ratings_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ratings Count","description":"How many ratings `rating` rests on (on eBay the seller's feedback score). Null when unknown; on Shein 1000 means at least 1000."},"sales_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sales Count","description":"Units sold where the retailer states it: AliExpress's lifetime sales, Amazon's monthly floor (100 = at least 100 bought last month). Null when unknown."},"pack_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pack Count","description":"The number of units in the listing's pack when stated (76 for a 76-count box). Null when unknown."},"unit_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit Size","description":"The size of one unit when stated, as text (\"5 fl oz\"). Null when unknown."},"normalized_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Normalized Price","description":"The price adjusted to the page product's quantity, which orders the listings when pack counts are known. Null when no adjustment applies."},"resolve_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolve Id","description":"An id to fetch the merchant's link with when `url` is null; valid for up to two hours after the search, sometimes less."},"coupon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Coupon","description":"A coupon's or promo code's saving as the retailer shows it (\"6% coupon\", \"$5.10 coupon\"); `price` already has it taken off. Null when there is none."},"promo_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Promo Code","description":"The code to type at the retailer's checkout for `coupon` (eBay today). Null otherwise."},"price_before_discount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Before Discount","description":"The listed price before the coupon or code was taken off. Null without a coupon."},"discount_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Discount Type","description":"How the retailer expresses the discount: \"percent\" or \"fixed\". Null without a coupon."},"discount_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Discount Value","description":"The discount's figure: the percentage for \"percent\" (6 for 6% off), the amount in `currency` for \"fixed\" (30 for $30 off). Null without a coupon."},"shipping_cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Shipping Cost","description":"What the retailer charges to ship this listing to an address in the market's country, in `currency`, without a paid membership: 0 when it ships free. Null when unknown. `price` does not include it."},"over_page_price":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Over Page Price","description":"True when this listing costs the same as the page or more (pack-adjusted), false when it is cheaper, null when the page's price was unknown."}},"additionalProperties":true,"type":"object","required":["title","price","image","retailer","over_page_price"],"title":"Card","description":"One listing of the product elsewhere: what it is, what it costs, where it is sold, and a link to buy it."},"CardRef":{"properties":{"list":{"type":"string","enum":["same_product","similar_products"],"title":"List","description":"The list the card is in: same_product or similar_products."},"position":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Position","description":"The card's place in that list, counting from 1."}},"type":"object","required":["list","position"],"title":"CardRef","description":"One card of a search answer, named by its list and its place in it."},"CheaperListing":{"properties":{"url":{"type":"string","title":"Url","description":"The cheaper listing's address."},"price":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Price","description":"Its price, in the market's currency. Null when you do not know it."}},"type":"object","required":["url"],"title":"CheaperListing","description":"A cheaper listing found elsewhere that the answer did not have."},"ErrorBody":{"properties":{"type":{"type":"string","title":"Type","description":"The error's kind: invalid_request, invalid_url, unknown_market, unauthorized, credits_exhausted, account_suspended, not_searchable, refused, rate_limited, unreachable, timeout, search_failed or account_service_unavailable; on a feedback call also search_not_found or feedback_off."},"message":{"type":"string","title":"Message","description":"One sentence saying what happened, for a person or an agent to read."},"credits_used":{"type":"integer","title":"Credits Used","description":"What the failed call cost: 1 for not_searchable and refused (the page was read before the search stopped), 0 for every other error."},"request_id":{"type":"string","title":"Request Id","description":"This call's id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call."}},"type":"object","required":["type","message","credits_used","request_id"],"title":"ErrorBody","description":"What every failed call answers, inside `error`."},"ErrorEnvelope":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody","description":"The error: its type, one sentence, what the call cost, the call's id."}},"type":"object","required":["error"],"title":"ErrorEnvelope","description":"Every /v1 error: an HTTP status and this one shape."},"ExtractIn":{"properties":{"url":{"type":"string","title":"Url","description":"The product page's address (https), as the shopper sees it."},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market","description":"The shopper's market, the country they are buying in: US, CA, AU, IN or GLOBAL. Omit it to infer the market from the address (a .in address is India, a .ca address Canada, and so on; every other address is the US)."}},"type":"object","required":["url"],"title":"ExtractIn"},"FeedbackAnswer":{"properties":{"request_id":{"type":"string","title":"Request Id","description":"This call's id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call."},"recorded":{"type":"boolean","title":"Recorded","description":"True when this report was recorded."},"already_reported":{"type":"boolean","title":"Already Reported","description":"True when the search already had a report: the first one stands and this one changed nothing."},"credits_refunded":{"type":"integer","title":"Credits Refunded","description":"The credits this report gave back to the account: 1 for the first report on a search, 0 for a later one or once the day's cap is reached."},"refunded_today":{"type":"integer","title":"Refunded Today","description":"The credits feedback has given back to the account so far today (UTC), this report's included."},"daily_refund_cap":{"type":"integer","title":"Daily Refund Cap","description":"The most credits feedback gives back to one account in a day (UTC)."},"daily_cap_reached":{"type":"boolean","title":"Daily Cap Reached","description":"True when the day's cap is reached: a report is still recorded and gives no credit back until the next day (UTC)."},"credits_used":{"type":"integer","title":"Credits Used","description":"The credits this call cost the account: 0, sending feedback costs nothing."}},"additionalProperties":true,"type":"object","required":["request_id","recorded","already_reported","credits_refunded","refunded_today","daily_refund_cap","daily_cap_reached","credits_used"],"title":"FeedbackAnswer","description":"Whether a report on a search was recorded, and the credit it gave back."},"FeedbackIn":{"properties":{"rating":{"type":"string","enum":["good","partial","bad"],"title":"Rating","description":"How the search went: good, partial or bad."},"useful_cards":{"anyOf":[{"items":{"$ref":"#/components/schemas/CardRef"},"type":"array","maxItems":20},{"type":"null"}],"title":"Useful Cards","description":"The cards you showed or recommended, each named by its list and its position in it."},"wrong_cards":{"anyOf":[{"items":{"$ref":"#/components/schemas/WrongCard"},"type":"array","maxItems":20},{"type":"null"}],"title":"Wrong Cards","description":"Cards that do not belong in their list, each named by its list and its position in it, with a reason."},"cheaper_elsewhere":{"anyOf":[{"items":{"$ref":"#/components/schemas/CheaperListing"},"type":"array","maxItems":20},{"type":"null"}],"title":"Cheaper Elsewhere","description":"Cheaper listings you found that the answer did not have, each with its address and its price."},"missing":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":20},{"type":"null"}],"title":"Missing","description":"What you expected and did not get, one short sentence each."},"goal":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Goal","description":"What the shopper was trying to do, in one sentence. Nothing personal about the shopper."},"note":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Note","description":"Anything else worth knowing about this search, short."}},"type":"object","required":["rating"],"title":"FeedbackIn","description":"How a search went: the rating and at least one other field."},"NextStep":{"properties":{"label":{"type":"string","title":"Label","description":"The step in a few words, as a person reads it. Also the words for a button."},"tool":{"type":"string","title":"Tool","description":"The MCP tool that runs it. On the API, find_cheaper is POST /v1/search with the same fields."},"arguments":{"additionalProperties":true,"type":"object","title":"Arguments","description":"The fields to send."},"choose":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Choose","description":"Only on a step that needs a choice, else null: the stores of this market, under `marketplaces`. Send the ones to keep as `marketplaces`, with the fields in `arguments`."}},"additionalProperties":true,"type":"object","required":["label","tool","arguments","choose"],"title":"NextStep","description":"One thing that can be done next for the product, with the call that does it."},"ProductRead":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The product's name as the page gives it. Null when the page did not state one."},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image","description":"The product's main photo. Null when the page did not show one."},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price","description":"The page's price, in `currency`. Null when the page did not state one, or stated it in another market's currency."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"The ISO 4217 code of `price`. Null when `price` is."},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand","description":"The product's brand when the page states it. Null otherwise."},"url":{"type":"string","title":"Url","description":"The page's address as read."},"market":{"type":"string","title":"Market","description":"The market the page was read in: US, CA, AU, IN or GLOBAL."},"in_stock":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"In Stock","description":"Whether the page says the product is in stock. Null when the page does not say."},"retailer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retailer","description":"The marketplace the page is a listing on, named as a listing's `retailer` is (\"Amazon\", \"Flipkart\", \"eBay\"). Null for any other store's page."},"coupon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Coupon","description":"A coupon or promo code the page offers on this product, by its saving as the retailer shows it (\"10% coupon\", \"$5 coupon\"). `price` is the page's price before the coupon or code. Null when none was found."},"promo_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Promo Code","description":"The code to type at the retailer's checkout for `coupon` (eBay today). Null otherwise."},"shipping_cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Shipping Cost","description":"What the retailer charges to ship this product to an address in the market's country, in `currency`, without a paid membership: 0 when it ships free. `price` does not include it. Null when unknown."},"returns_accepted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Returns Accepted","description":"Whether the seller takes the product back (eBay listings today). Null when unknown."},"return_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Return Days","description":"How many days the buyer has to send the product back. Null when returns are not accepted or the period is unknown."},"return_shipping_paid_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Return Shipping Paid By","description":"Who pays the postage to send the product back: \"buyer\" or \"seller\". Null when unknown."},"pack_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pack Count","description":"The number of units in the page product's pack (42 for a 42-count tub): the quantity each listing's `normalized_price` is adjusted to. Null when the page sells a single item or no count could be read."}},"additionalProperties":true,"type":"object","required":["title","image","price","currency","brand","url","market","in_stock"],"title":"ProductRead","description":"The page as read, which the search compared against."},"ReadAnswer":{"properties":{"request_id":{"type":"string","title":"Request Id","description":"This call's id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call."},"is_product_page":{"type":"boolean","title":"Is Product Page","description":"True when the page sells one product that could be read: a title and a photo at least."},"url":{"type":"string","title":"Url","description":"The page's address as read."},"market":{"type":"string","title":"Market","description":"The market the page was read in: US, CA, AU, IN or GLOBAL."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The product's name as the page gives it. Null when the page did not state one."},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image","description":"The product's main photo. Null when the page did not show one."},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price","description":"The page's price, in `currency`. Null when the page did not state one, or stated it in another market's currency."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"The ISO 4217 code of `price`. Null when `price` is."},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand","description":"The product's brand when the page states it. Null otherwise."},"in_stock":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"In Stock","description":"Whether the page says the product is in stock. Null when the page does not say."},"retailer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retailer","description":"The marketplace the page is a listing on, named as a listing's `retailer` is (\"Amazon\", \"Flipkart\", \"eBay\"). Null for any other store's page."},"coupon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Coupon","description":"A coupon or promo code the page offers on this product, by its saving as the retailer shows it (\"10% coupon\", \"$5 coupon\"). `price` is the page's price before the coupon or code. Null when none was found."},"promo_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Promo Code","description":"The code to type at the retailer's checkout for `coupon` (eBay today). Null otherwise."},"shipping_cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Shipping Cost","description":"What the retailer charges to ship this product to an address in the market's country, in `currency`, without a paid membership: 0 when it ships free. `price` does not include it. Null when unknown."},"returns_accepted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Returns Accepted","description":"Whether the seller takes the product back (eBay listings today). Null when unknown."},"return_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Return Days","description":"How many days the buyer has to send the product back. Null when returns are not accepted or the period is unknown."},"return_shipping_paid_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Return Shipping Paid By","description":"Who pays the postage to send the product back: \"buyer\" or \"seller\". Null when unknown."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why the page is not a readable product page: gone, incomplete, price_in_another_currency or not_a_product_page. Null on a clean product read."},"next_steps":{"items":{"$ref":"#/components/schemas/NextStep"},"type":"array","title":"Next Steps","description":"What can be done next for this product, each with the call that does it. Use these yourself when it serves the task the user gave you, or offer them to the user as next steps. Each runs a search. Empty when nothing applies."},"credits_used":{"type":"integer","title":"Credits Used","description":"The credits this call cost the account: 1 for a page read, whether or not the page sells a product."}},"additionalProperties":true,"type":"object","required":["request_id","is_product_page","url","market","title","image","price","currency","brand","in_stock","reason","credits_used"],"title":"ReadAnswer","description":"What a product page sells, as read, without a search."},"ResolveAnswer":{"properties":{"request_id":{"type":"string","title":"Request Id","description":"This call's id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call."},"resolved":{"type":"boolean","title":"Resolved","description":"True when the merchant's link was found."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The merchant's link to the listing. Null when not resolved. On the Free plan it may be an affiliate link."},"retailer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retailer","description":"The merchant's name. Null when not resolved."},"credits_used":{"type":"integer","title":"Credits Used","description":"The credits this call cost the account: 1 when a link came back, 0 when the id could not be resolved."}},"additionalProperties":true,"type":"object","required":["request_id","resolved","url","retailer","credits_used"],"title":"ResolveAnswer","description":"The merchant's link for a card that came with a resolve_id instead of a url."},"ResolveIn":{"properties":{"id":{"type":"string","title":"Id","description":"The resolve_id of a search card whose url is null."}},"type":"object","required":["id"],"title":"ResolveIn"},"SameProductCard":{"properties":{"title":{"type":"string","title":"Title","description":"The listing's title, as the retailer shows it."},"price":{"type":"number","title":"Price","description":"The live, buyable price of the item alone, without shipping, in `currency`. When `coupon` is set, this is the price after the coupon or code."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"The ISO 4217 code of `price` (USD, CAD, AUD, INR). Null means the market's currency."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The listing's link. Null when the link must be fetched first with `resolve_id` (resolve_listing on the MCP server, POST /v1/resolve on the API). On the Free plan it may be an affiliate link."},"image":{"type":"string","title":"Image","description":"The listing's photo."},"retailer":{"type":"string","title":"Retailer","description":"Where the product is sold: Amazon, Walmart, eBay, AliExpress, Shein, Flipkart, or the store's name for a listing found across the web."},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating","description":"The retailer's rating: stars out of 5 on most retailers; on eBay the seller's positive-feedback percentage (0 to 100). Null when unknown."},"ratings_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ratings Count","description":"How many ratings `rating` rests on (on eBay the seller's feedback score). Null when unknown; on Shein 1000 means at least 1000."},"sales_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sales Count","description":"Units sold where the retailer states it: AliExpress's lifetime sales, Amazon's monthly floor (100 = at least 100 bought last month). Null when unknown."},"pack_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pack Count","description":"The number of units in the listing's pack when stated (76 for a 76-count box). Null when unknown."},"unit_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit Size","description":"The size of one unit when stated, as text (\"5 fl oz\"). Null when unknown."},"normalized_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Normalized Price","description":"The price adjusted to the page product's quantity, which orders the listings when pack counts are known. Null when no adjustment applies."},"resolve_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolve Id","description":"An id to fetch the merchant's link with when `url` is null; valid for up to two hours after the search, sometimes less."},"coupon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Coupon","description":"A coupon's or promo code's saving as the retailer shows it (\"6% coupon\", \"$5.10 coupon\"); `price` already has it taken off. Null when there is none."},"promo_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Promo Code","description":"The code to type at the retailer's checkout for `coupon` (eBay today). Null otherwise."},"price_before_discount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Before Discount","description":"The listed price before the coupon or code was taken off. Null without a coupon."},"discount_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Discount Type","description":"How the retailer expresses the discount: \"percent\" or \"fixed\". Null without a coupon."},"discount_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Discount Value","description":"The discount's figure: the percentage for \"percent\" (6 for 6% off), the amount in `currency` for \"fixed\" (30 for $30 off). Null without a coupon."},"shipping_cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Shipping Cost","description":"What the retailer charges to ship this listing to an address in the market's country, in `currency`, without a paid membership: 0 when it ships free. Null when unknown. `price` does not include it."},"over_page_price":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Over Page Price","description":"True when this listing costs the same as the page or more (pack-adjusted), false when it is cheaper, null when the page's price was unknown."}},"additionalProperties":true,"type":"object","required":["title","price","image","retailer","over_page_price"],"title":"SameProductCard","description":"A listing that matches the original product, with whether it beats the page's price."},"SearchAnswer":{"properties":{"request_id":{"type":"string","title":"Request Id","description":"This call's id (a UUID), the one on the account's usage ledger. Quote it when writing to support about the call."},"search":{"$ref":"#/components/schemas/SearchEcho","description":"What was searched: the address as sent, the market the search ran in, the condition. Read it before the cards."},"product":{"$ref":"#/components/schemas/ProductRead","description":"The page as read."},"product_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Name","description":"The product's short name as the search identified it (\"Sony WH-1000XM6\"). Null when it could not be named."},"about_lists":{"type":"string","title":"About Lists","description":"What the two lists hold for this search, in a sentence or two. Read it before the lists. Both lists come already matched and in order: show them as they are and do not re-check or re-sort them yourself."},"same_product":{"items":{"$ref":"#/components/schemas/SameProductCard"},"type":"array","title":"Same Product","description":"Listings that match the original product, cheapest first, up to 10; the ones cheaper than the page come first, then the ones at or over its price. `about_lists` says what counts as a match for this search."},"similar_products":{"items":{"$ref":"#/components/schemas/Card"},"type":"array","title":"Similar Products","description":"Acceptable equivalents of the original product, cheapest first, up to 10. Use or show first the ones that cost less than the page (`over_page_price` false). The ones at or over its price are for a shopper or a task that wants alternatives whatever the price. `about_lists` says what this list holds for this search."},"page_is_cheapest":{"type":"boolean","title":"Page Is Cheapest","description":"True when the page already has the lowest price the search found for the product."},"next_steps":{"items":{"$ref":"#/components/schemas/NextStep"},"type":"array","title":"Next Steps","description":"What can be done next for this product, each with the call that does it. Use these yourself when it serves the task the user gave you, or offer them to the user as next steps. Each runs another search. Empty when nothing applies."},"credits_used":{"type":"integer","title":"Credits Used","description":"The credits this call cost the account: 10 for a search."}},"additionalProperties":true,"type":"object","required":["request_id","search","product","product_name","about_lists","same_product","similar_products","page_is_cheapest","next_steps","credits_used"],"title":"SearchAnswer","description":"Where the product on a page is sold for less. In order: the call's\nid, what was searched, the page as read, the product's name, what the\ntwo lists hold, the listings that match the original product,\nacceptable equivalents, whether the page is already the cheapest, what\ncan be done next, and what the call cost."},"SearchEcho":{"properties":{"url":{"type":"string","title":"Url","description":"The product page's address, as sent."},"market":{"type":"string","title":"Market","description":"The market the search ran in: US, CA, AU, IN or GLOBAL — the one sent, or the one inferred from the address when none was."},"condition":{"type":"string","enum":["new","used"],"title":"Condition","description":"new or used, as sent (new when none was)."},"max_results":{"type":"integer","title":"Max Results","description":"The cap on each list, 1 to 10: the one sent, or 10 when none was."}},"additionalProperties":true,"type":"object","required":["url","market","condition","max_results"],"title":"SearchEcho","description":"The search as the agent took it: what was searched, before the\nresults. Which marketplaces it was routed to is not told."},"SearchIn":{"properties":{"url":{"type":"string","title":"Url","description":"The product page's address (https), as the shopper sees it."},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market","description":"The shopper's market, the country they are buying in: US, CA, AU, IN or GLOBAL. Omit it to infer the market from the address (a .in address is India, a .ca address Canada, and so on; every other address is the US)."},"marketplaces":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Marketplaces","description":"Which marketplaces to search, from amazon, walmart, ebay, aliexpress, shein, flipkart and other_sites (every other store). Only the ones available in the market count. Omit it to let the agent choose for the product."},"condition":{"type":"string","enum":["new","used"],"title":"Condition","description":"new (the default) finds the product new; used finds it secondhand. A used search is not available in India and is refused for grocery and consumable products.","default":"new"},"max_results":{"anyOf":[{"type":"integer","maximum":10.0,"minimum":1.0},{"type":"null"}],"title":"Max Results","description":"How many listings at most in each list, 1 to 10; 10 when omitted. Ask for fewer when only the cheapest few matter. The credits are the same whatever the cap."}},"type":"object","required":["url"],"title":"SearchIn"},"WrongCard":{"properties":{"list":{"type":"string","enum":["same_product","similar_products"],"title":"List","description":"The list the card is in: same_product or similar_products."},"position":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Position","description":"The card's place in that list, counting from 1."},"reason":{"type":"string","enum":["different_product","not_equivalent","price_differs","unavailable","other"],"title":"Reason","description":"Why the card does not belong: different_product (it is not the product the page sells), not_equivalent (it is not an acceptable equivalent), price_differs (the listing's price is not the card's), unavailable (the listing is gone or out of stock) or other."}},"type":"object","required":["list","position","reason"],"title":"WrongCard","description":"A card that does not belong in its list, and why."}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key from the dashboard (https://findcheap.ai/dashboard/keys): `Authorization: Bearer fc_live_…`."}}}}