> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archeraffiliates.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Product deals

> Find confirmed product deals, filter discounts, and understand deal prices.

Both [Browse the product catalog](https://docs.archeraffiliates.com/publisher-api/products/browse-the-product-catalog.md)
and [Look up one product by ASIN](https://docs.archeraffiliates.com/publisher-api/products/look-up-one-product-by-asin.md)
return a `deal` object, or `null` when no eligible confirmed deal exists.

## Find deals

```bash theme={null}
curl "https://api.archeraffiliates.com/getproducts?marketplace=amazon.co.uk&deals_only=true&min_discount_percent=20&max_discount_percent=70&sort_by=deal_percent_high_to_low&skip=0&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

| Parameter | Behavior |
| - | - |
| `deals_only` | Defaults to `false`. Set `true` to return only available products with a valid deal. |
| `min_discount_percent` | Inclusive minimum, integer 0-100. |
| `max_discount_percent` | Inclusive maximum, integer 0-100. |
| `sort_by=deal_percent_high_to_low` | Highest discount percentage first. |
| `sort_by=deal_savings_high_to_low` | Highest `was_price - current_price` first. |

Either discount bound or either deal sort implies deals-only, even when
`deals_only` is omitted or false. A minimum greater than the maximum returns
HTTP 400; invalid bounds or sort values return HTTP 422. Equal bounds are valid.
The existing marketplace, search, brand, ASIN, and pagination filters still apply.
`product_available=no` combined with deal filtering returns no matches.

The list response keeps `total_count`, `fetched_count`, `skip`, `limit`, and
`product_catalog`. The single-product endpoint returns the product object directly;
it does not accept the list's deal filters or sorting options.

## Deal response

Illustrative product excerpt (prices use the product's `pricing.currency`):

```json theme={null}
{
  "ASIN": "B01KZNZ4CA",
  "marketplace": "amazon.co.uk",
  "pricing": { "price": 2.99, "currency": "GBP" },
  "deal": {
    "discount_percent": 65,
    "current_price": 2.99,
    "was_price": 8.62,
    "avg_last_30_day_price": 8.62,
    "list_price": 17.97,
    "coupon": { "type": "percent", "value": 5 },
    "is_lightning": false,
    "ends_at": null,
    "prime_exclusive": false,
    "last_updated": "2026-10-28T03:00:00Z"
  }
}
```

| Field | Meaning |
| - | - |
| `discount_percent` | Rounded percentage reduction from `was_price` to `current_price`. |
| `current_price` | Price recorded in the confirmed deal snapshot. |
| `was_price` | Discount reference: the lower of the available list price and 30-day average. It is not necessarily the immediately previous selling price. |
| `avg_last_30_day_price` | Average price over the last 30 days; nullable. |
| `list_price` | Seller list/reference price in the deal snapshot; nullable. |
| `coupon` | Optional `{type, value}`. Type is `percent` or `absolute`; absolute amounts use `pricing.currency`. |
| `is_lightning` | Whether the snapshot represents a lightning deal. |
| `ends_at` | Known expiry as a UTC timestamp, otherwise `null`. |
| `prime_exclusive` | Whether the deal price requires Prime; other customers may see a higher price. |
| `last_updated` | UTC timestamp when the deal was last confirmed. |

For list price 17.97, average price 8.62 and current price 2.99, the reference
`was_price` is 8.62 and the discount is approximately 65%. Coupon savings are
not automatically subtracted from `current_price` or included in savings sorting.

Catalog `price` / `pricing.price` and top-level `list_price` may differ from deal
snapshot prices. Use `deal.was_price` and `deal.current_price` together for deal
savings. Savings sorting compares amounts in their local currencies without
currency conversion, so select one marketplace for meaningful comparisons.

## Freshness and availability

`deal` is `null` for missing or invalid snapshots, unavailable products, snapshots
older than 24 hours, or expired deals. Lightning deals require a known future end
time. A null end time for a non-lightning deal does not guarantee indefinite
availability. Deal filters and counts use the same validity rules.

The public field names are `deal`, `avg_last_30_day_price`, and `last_updated`.
Internal storage field names are not returned in the response.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.