# Get the deals feed

> GET /v1/deals returns current deals with expert grades, community votes, hot/new/top sorting and filters for category, retailer, price and grade.

*Source: https://shopsavvy.com/data/documentation/deals* · Part of the [ShopSavvy Data API documentation](https://shopsavvy.com/data/documentation.md)

---

Retrieve a feed of current shopping deals with Reddit-style sorting, filtering, and pagination. Each deal includes an expert grade (A+ through F), pricing, retailer info, community votes, and more.

**Endpoint:** `GET /v1/deals`

**Credit Cost:** 1 credit per 10 deals returned

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `sort` | string | `hot` | Sort algorithm: `hot`, `new`, `top-hour`, `top-day`, `top-week` |
| `limit` | number | 25 | Results per page (1-100) |
| `offset` | number | 0 | Pagination offset |
| `category` | string | | Filter by product category |
| `retailer` | string | | Filter by retailer domain (e.g., `amazon.com`) |
| `tag` | string | | Filter by deal tag |
| `min_price` | number | | Minimum deal price |
| `max_price` | number | | Maximum deal price |
| `grade` | string | | Minimum grade: `A`, `B`, `C`, `D` |
| `format` | string | `json` | Response format: `json` or `csv` |

**Boolean Filters** (set to `true` to filter): `is_percentage_off`, `is_dollar_off`, `is_bogo`, `is_price_drop`, `is_free_shipping`, `is_fast_shipping`, `is_limited_time`, `is_clearance`, `is_new_product`, `is_bundle`, `is_refurbished`, `is_open_box`, `requires_membership`, `has_coupon_code`, `has_mail_in_rebate`

**Example Request:**

```bash
curl -X GET 'https://api.shopsavvy.com/v1/deals?sort=hot&limit=10&grade=B' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

**Example Response:**

```json
{
  "success": true,
  "deals": [
    {
      "path": "deals/abc123",
      "title": "Sony WH-1000XM5 Wireless Headphones - 25% Off",
      "subtitle": "Lowest price in 3 months",
      "description": "Industry-leading noise cancellation headphones at a rare discount...",
      "emoji": "🎧",
      "grade": { "letter": "A", "suffix": "+", "value": 0.98, "justification": "Excellent price on a top-rated product" },
      "pricing": { "current": 248.00, "original": 349.99, "currency": "USD" },
      "retailer": { "name": "Amazon" },
      "url": "https://...",
      "image": { "url": "https://..." },
      "votes": {
        "upvotes": 142,
        "downvotes": 3,
        "score": 139,
        "upvotes_internal": 6,
        "downvotes_internal": 1,
        "score_internal": 5,
        "upvotes_external": 136,
        "downvotes_external": 2,
        "score_external": 134
      },
      "comment_count": 23,
      "comment_count_community": 2,
      "tags": [{ "slug": "electronics", "display": "Electronics" }],
      "expires_at": "2026-04-15T00:00:00Z",
      "created_at": "2026-03-28T12:00:00Z"
    }
  ],
  "pagination": { "total": 487, "has_more": true, "limit": 10, "offset": 0 },
  "meta": { "request_id": "abc-123", "credits_used": 1, "credits_remaining": 999 }
}
```

**Vote and comment provenance**

Deals reach ShopSavvy two ways: posted by ShopSavvy users, and imported from public
deal communities. Engagement numbers on an imported deal carry over from its source,
so the top-level totals mix both populations. Read the breakdown when you need one or
the other:

| Field | Meaning |
|-------|---------|
| `votes.upvotes` / `downvotes` / `score` | Combined totals. Equals internal + external. |
| `votes.upvotes_internal` / `downvotes_internal` / `score_internal` | Votes cast by ShopSavvy accounts only. |
| `votes.upvotes_external` / `downvotes_external` / `score_external` | Engagement carried over from the deal's source at import time. |
| `comment_count` | Every comment on the deal thread. |
| `comment_count_community` | Comments written by ordinary ShopSavvy accounts, excluding ShopSavvy's own editorial personas. |

On the current corpus the external component dominates the combined totals by a wide
margin, so treat `score` as "how much attention this deal has attracted anywhere"
rather than "how many ShopSavvy users voted." Use `score_internal` /
`comment_count_community` for the latter. The same split is available in the CSV
export as `votes_up_internal`, `votes_down_internal`, `votes_up_external`,
`votes_down_external`, `comment_count` and `comment_count_community`.