> Documentation index: https://docs.scrapier.io/llms.txt
> Auth: header `X-API-Key: <key>` · Base: https://api.scrapier.io/api/v2 · Synchronous; paginate with `cursor` ← `data.next_cursor`.

# Amazon Today's Deals

List Amazon's current deals with price, price before the discount, savings, rating and review count. Filters are optional.

`GET|POST https://api.scrapier.io/api/v2/amazon-todays-deals/` · 1 credit per successful call · Cursor-paginated

## Overview

Call it with no parameters to get the deals Amazon currently lists, each with ASIN, title, link, price to pay, price before the discount, savings amount and percentage, deal type and state, rating, review count and image.

Narrow the list on the first call with `department`, `deal_type` (`all`, `best_deal`, `lightning_deal` or `coupon`), `prime_exclusive`, `min_discount` and `max_discount` (percent) and `min_price` and `max_price` (USD). The filters are locked into the cursor. Page through the deals by passing `next_cursor` back as `cursor`.

## Use cases

- Watch daily discounts in categories you sell in.
- Alert on deals for products you track.
- Feed a deals newsletter or channel.

## Request

```bash
curl -G "https://api.scrapier.io/api/v2/amazon-todays-deals/" \
  -H "X-API-Key: YOUR_API_KEY" \
  --max-time 210
```

```python
import requests

resp = requests.get(
    "https://api.scrapier.io/api/v2/amazon-todays-deals/",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={},
    timeout=210,
)
body = resp.json()
if not resp.ok:
    raise RuntimeError(body.get("error") or body.get("detail"))

print(body["data"]["deals"])
```

POST with a JSON body works too (same parameters; the body is merged over the query string).

## Parameters

> **Note:** No parameter is strictly required, but send at least the inputs shown in the example.

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `X-API-Key` (header) | string | yes | — | Your API key. |
| `cursor` | string | no | — | Pagination cursor returned in the previous response's `next_cursor`. Pass it back unchanged to fetch the next page. When `next_cursor` is null, you have reached the last page. |
| `department` | string | no | — | First call only (locked into the cursor). Optional department name (e.g. Electronics, Home & Kitchen, Books, Toys & Games) or Amazon browse-node id. Empty = all. |
| `deal_type` | string | no | `all` | First call only. all \| best_deal \| lightning_deal \| coupon. One of: `all`, `best_deal`, `lightning_deal`, `coupon`. |
| `prime_exclusive` | boolean | no | `false` | First call only. Only Prime-exclusive deals |
| `min_discount` | integer | no | — | First call only. Minimum discount % (0-100) |
| `max_discount` | integer | no | — | First call only. Maximum discount % (0-100) |
| `min_price` | integer | no | — | First call only. Minimum price in USD |
| `max_price` | integer | no | — | First call only. Maximum price in USD |
| `use_proxy` | boolean | no | `true` | Route the request through Scrapier's residential proxy pool. Default: `true`. Leave as is unless support tells you otherwise. |
| `raw_data` | boolean | no | `false` | When true, the response carries the full raw upstream payload(s) the scraper received (GraphQL / JSON API bodies, HTML, embedded JSON-LD -- exactly as the platform returned them) under `raw_responses`, in place of the formatted items. When false (default) you get the formatted output. Pagination (`cursor` / `next_cursor`) works the same in both modes. |

## Response

HTTP 200. Results are in `data.deals`. Sample from the live catalog, arrays trimmed to 3 items.

```json
{
  "success": true,
  "data": {
    "index": 0,
    "page_size": 60,
    "deals": [
      {
        "asin": "B0GZTKN3MN",
        "basis_price": 1099.99,
        "price_to_pay": 749,
        "currency": "USD",
        "savings_amount": 350.99,
        "savings_percentage_value": 32,
        "title": "ECOVACS DEEBOT Robot Vacuum and Mop, X11S OMNICYCLONE",
        "link": "https://www.amazon.com/ECOVACS-DEEBOT-Robot-Vacuum-OMNICYCLONE/dp/B0GZTKN3MN",
        "deal_state": "AVAILABLE",
        "deal_type": "BEST_DEAL",
        "image": "https://m.media-amazon.com/images/I/71FQzChMWDL.jpg",
        "rating": 4.6,
        "reviews_count": 83
      }
    ],
    "next_cursor": "zc1.eNrtwTEBAAAAwqD1T20KP6AAAAAAAAAA..."
  }
}
```

## Response fields

| Field | Type | Example | Description |
|---|---|---|---|
| `index` | integer | `0` |  |
| `page_size` | integer | `60` |  |
| `deals` | array | `[1 item]` | The results. |
| `next_cursor` | string | `zc1.eNrtwTEBAAAAwqD1T20KP6AAAAAAAAAA...` | Pass back as `cursor` for the next page. `null` on the last page. |
| `deals[].asin` | string | `B0GZTKN3MN` |  |
| `deals[].basis_price` | number | `1099.99` | Price before the discount. |
| `deals[].price_to_pay` | integer | `749` | Price you pay for the deal. |
| `deals[].currency` | string | `USD` |  |
| `deals[].savings_amount` | number | `350.99` | Amount saved against the price before the discount. |
| `deals[].savings_percentage_value` | integer | `32` | Discount in percent. |
| `deals[].title` | string | `ECOVACS DEEBOT Robot Vacuum and Mop, X11S OMN…` |  |
| `deals[].link` | string | `https://www.amazon.com/ECOVACS-DEEBOT-Robot-V…` | Link to the product page. |
| `deals[].deal_state` | string | `AVAILABLE` | Whether the deal is currently available. |
| `deals[].deal_type` | string | `BEST_DEAL` | Kind of deal, for example BEST_DEAL. |
| `deals[].image` | string | `https://m.media-amazon.com/images/I/71FQzChMW…` |  |
| `deals[].rating` | number | `4.6` |  |
| `deals[].reviews_count` | integer | `83` |  |

## Pagination

Pass `data.next_cursor` back as `cursor` until it is `null`. Required inputs are ignored once a cursor is sent. Each page is one billed call.

```python
import requests

URL = "https://api.scrapier.io/api/v2/amazon-todays-deals/"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
params = {}
items = []

for _ in range(10):  # each page is one billed call
    resp = requests.get(URL, headers=HEADERS, params=params, timeout=210)
    resp.raise_for_status()
    data = resp.json()["data"]
    items.extend(data.get("deals") or [])
    if not data.get("next_cursor"):  # None = last page
        break
    params = {"cursor": data["next_cursor"]}
```

## Errors

Failed calls are free. Branch on HTTP status; the message is in `error` (or `detail`). See https://docs.scrapier.io/errors.md

- **400** Bad input. The exact message varies by endpoint. `{"success":false,"error":"…"}`
- **402** Balance below the endpoint's price. `{"error":"Insufficient credits. Buy more to scrape more.","balance":1,"required":2}`
- **403** Invalid or unknown API key. `{"detail":"Authentication service unavailable or invalid API key."}`
- **429** Throttled — wait for Retry-After. `{"detail":"Request was throttled. Expected available in N seconds."}`
- **404** unknown slug · **503** busy (retry after `Retry-After`) · **5xx** upstream failure or timeout (retry with backoff).

## Notes

- No input is required; every filter is optional.
- The filters (`department`, `deal_type`, `prime_exclusive`, `min_discount`, `max_discount`, `min_price`, `max_price`) are read on the first call only and locked into the cursor.

## Related

- [Amazon Best Sellers](https://docs.scrapier.io/api-reference/amazon/amazon-bestsellers.md): Get ranked products from an Amazon Best Sellers category URL, with price, rating, review count and list position.
- [Amazon Search](https://docs.scrapier.io/api-reference/amazon/amazon-search.md): Search Amazon by keyword and get product results with price, rating and position, with marketplace and sort order options.
- [Amazon Products](https://docs.scrapier.io/api-reference/amazon/amazon-product.md): Search Amazon by keyword or URL and get product listings, or send a product URL to get that single product.
