deals
Fetch live Amazon sale listings filtered by department, discount, price, rating, brand, or collection to find current discounts, Lightning offers, coupons, and Prime-only items.
Instructions
LIVE Amazon Today's Deals: the deals page of one marketplace, read from Amazon at request time and filtered the way Amazon's own page filters it - department (category_id), deal collection (deal_types: lightning_deal, trending, coupons, started_today, ending_today; or any collection id an answer lists), percent off, price, Prime Exclusive, minimum rating, brand. USE WHEN the user asks what is on sale or discounted on Amazon right now, wants today's deals or lightning deals in a department, deals above a discount or under a price, coupon deals, or deals ending today. DON'T USE for one product's price history or past price drops (product with offer_history), for who sells a product right now (offers), for a keyword search (serp, shopping) or for what sells best in a category (bestsellers). RETURNS deals[] (position, asin, title, link, image, deal_id, deal_link, deal_type e.g. BEST_DEAL / LIGHTNING_DEAL, is_lightning_deal, deal_state, percent_claimed, ends_at, deal_price and list_price {value, currency, symbol, label}, percent_off, savings, deal_badge, is_prime_price, coupon {text, amount, promotion_id, link}, brand, brand_id, department_ids, product_group, product_type, variations), categories[] (category_id, name, selected: the departments to pass back as category_id), collections[] (id, name: pass back as collection), facets (brands with ids, reviewRating, price and percentOff ranges, accessType), selected_filters, filter_check (per requested filter: applied / not_applied / unverified), pagination (page, page_size, pages_fetched, start_index, returned, has_more, partial), amazon (marketplace_id, locale, currency), observed_at and cached. HONESTY: an empty deals list is a real answer (e.g. no lightning deals running at this hour); a filter Amazon did not apply (filter_check not_applied, e.g. a category_id that is not one of the marketplace's deals departments) is refused as an error, never billed, instead of serving the unfiltered page; unverified filters are served, so say so before relying on them; there is no total count (has_more says whether the last page came back full) and no deal start time; ends_at only where Amazon shows a countdown; list_price is Amazon's reference price with its own label (RRP, Was, Typical ...), null when the page shows none. LATENCY is SECONDS: ~10-30s a page (pages=5 up to ~2 min); an identical request within 15 min may come from our cache in milliseconds. MARKETPLACES us, uk, de, ca, au, fr, it, es, jp, mx, br (no Walmart). COST API key required (the free no-signup lane cannot run live fetches). 1 credit per deals page fetched that returned at least one deal, whatever its size (30, 60, 90 or 120 deals are all 1 credit, so page_size=120 gives the most deals per credit), cached or fresh; a page with no deals, an empty list, a blocked or busy fetch and bad input are never billed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Optional: an Amazon deals URL (/deals, /events/deals or /gp/goldbox). The host decides the marketplace and its query string is kept (e.g. a filtered deals page copied from the browser). | |
| page | No | 1-based page of the deals list. | |
| brand | No | A brand id from facets.brands of a previous answer (e.g. 811979|dreame). | |
| pages | No | Consecutive pages merged into one answer, starting at page (stops early on a short page). 1 credit per page that returned deals. | |
| country | No | The Amazon marketplace whose deals page to read. Required unless url is given; with url it must match the URL's marketplace. | |
| discount | No | Rainforest form of min_discount (50_percent_off = at least 50% off). Not together with min_discount. | |
| max_price | No | Maximum deal price in the marketplace currency (Amazon applies whole units; a fraction is rounded up). | |
| min_price | No | Minimum deal price in the marketplace currency (Amazon applies whole units; a fraction is rounded down). | |
| page_size | No | Deals per page; Amazon serves steps of 30 only. Every page is 1 credit whatever its size, so 120 gives the most deals per credit. | |
| collection | No | Any other collection id from collections[] of a previous answer (collections differ per marketplace and over time). Not together with deal_types. | |
| deal_types | No | One of Amazon's stable deal collections. Not together with collection. | |
| category_id | No | A deals department id from categories[] of a previous answer (Amazon applies one department at a time). | |
| max_discount | No | Maximum percent off (0-100). | |
| min_discount | No | Minimum percent off (0-100). | |
| minimum_rating | No | Only products rated at least this many stars (1-4). | |
| prime_exclusive | No | true = Prime Exclusive deals only. |