Browsing Deals

By accessing our deals, you can find products that recently changed and match your search criteria. A single request will return a maximum of 150 deals. A query can provide up to 10,000 ASINs using paging. We recommend trying out our deals page first to familiarize yourself with the options and results before reading this documentation.

Endpoint#

You can choose between an HTTP GET or POST request. Both take the same queryJSON object, described below.

GET format#

POST format#

The queryJSON Object#

The query JSON contains all request parameters. Its full structure:

{
  "page": Integer,
  "domainId": Integer,
  "excludeCategories": [Long],
  "includeCategories": [Long],
  "priceTypes": [Integer],
  "deltaRange": [Integer],
  "deltaPercentRange": [Integer],
  "deltaLastRange": [Integer],
  "salesRankRange": [Integer],
  "currentRange": [Integer],
  "minRating": Integer,
  "isLowest": Boolean,
  "isLowest90": Boolean,
  "isLowestOffer": Boolean,
  "isHighest": Boolean,
  "isOutOfStock": Boolean,
  "isBackInStock": Boolean,
  "titleSearch": String,
  "isRangeEnabled": Boolean,
  "isFilterEnabled": Boolean,
  "hasReviews": Boolean,
  "filterErotic": Boolean,
  "singleVariation": Boolean,
  "isRisers": Boolean,
  "isPrimeExclusive": Boolean,
  "mustHaveAmazonOffer": Boolean,
  "mustNotHaveAmazonOffer": Boolean,
  "warehouseConditions": [Integer],
  "material": [String],
  "type": [String],
  "manufacturer": [String],
  "brand": [String],
  "model": [String],
  "color": [String],
  "size": [String],
  "unitType": [String],
  "scent": [String],
  "itemForm": [String],
  "pattern": [String],
  "style": [String],
  "itemTypeKeyword": [String],
  "targetAudienceKeyword": [String],
  "edition": [String],
  "format": [String],
  "author": [String],
  "binding": [String],
  "languages": [String],
  "brandStoreName": [String],
  "brandStoreUrlName": [String],
  "websiteDisplayGroup": [String],
  "websiteDisplayGroupName": [String],
  "salesRankDisplayGroup": [String],
  "sortType": Integer,
  "dateRange": Integer
}

Parameters#

Core parameters#

Valid domainId values

Valid priceTypes values

Valid dateRange values

Filter options#

Product attribute filters

These filters match products by their listing attributes. Each is an array of strings; the examples below show typical values.

Range options#

All range options are integer arrays with two entries: [min, max].

Search and sort options#

Valid sortType values

Token Cost#

5 tokens per request, providing up to 150 deals. To retrieve more than 150 results, issue additional requests with an incremented page parameter (5 tokens each); a single query can provide up to 10,000 ASINs this way.

Response#

The response contains a deals field with the following content:

{
  "dr": [deal objects],
  "categoryIds": [Long],
  "categoryNames": [String],
  "categoryCount": [Integer]
}

Example of one index: ID 165793011, name "Toys & Games", count 40. For more information about categories, visit the Category Object page.

Examples#

Example queryJSON#

A complete query selecting Amazon-price deals on amazon.com from one included root category, sorted by percentage delta over the last week:

{
  "page": 0,
  "domainId": 1,
  "excludeCategories": [1064954, 11091801],
  "includeCategories": [16310101],
  "priceTypes": [0],
  "deltaRange": [0, 10000],
  "deltaPercentRange": [20, 100],
  "deltaLastRange": null,
  "salesRankRange": [0, 40000],
  "currentRange": [500, 40000],
  "minRating": -1,
  "isLowest": false,
  "isLowestOffer": false,
  "isOutOfStock": false,
  "titleSearch": null,
  "isRangeEnabled": true,
  "isFilterEnabled": false,
  "filterErotic": true,
  "hasReviews": false,
  "singleVariation": true,
  "sortType": 4,
  "dateRange": 1
}

Example request#

Using GET, the queryJSON must be URL-encoded and passed in the selection parameter. A minimal query {"page":0,"domainId":1,"priceTypes":[0],"dateRange":1} becomes:

curl -s "https://api.keepa.com/deal?key=YOUR_API_KEY&selection=%7B%22page%22%3A0%2C%22domainId%22%3A1%2C%22priceTypes%22%3A%5B0%5D%2C%22dateRange%22%3A1%7D"

Using POST, the query is sent as the request payload — usually the more convenient option for larger queries:

KeepaAPI api = new KeepaAPI("YOUR_API_KEY");
DealRequest dealQuery = new DealRequest();
dealQuery.page = 0;
dealQuery.domainId = 1;               // amazon.com
dealQuery.priceTypes = new int[]{0};  // AMAZON price type
dealQuery.dateRange = 1;              // interval: last week
dealQuery.isRangeEnabled = true;
dealQuery.currentRange = new int[]{500, 40000};
dealQuery.deltaPercentRange = new int[]{20, 100};
dealQuery.sortType = 4;
api.sendRequest(Request.getDealsRequest(dealQuery))
    .done(result -> {
        for (Deal deal : result.deals.dr) {
            System.out.println(deal.asin + "  " + deal.title);
        }
    })
    .fail(failure -> System.out.println(failure));

<?php
use Keepa\KeepaAPI;
use Keepa\API\Request;
use Keepa\API\ResponseStatus;
use Keepa\objects\AmazonLocale;

use Keepa\API\DealRequest;
$api = new KeepaAPI("YOUR_API_KEY");
$dealQuery = new DealRequest();
$dealQuery->page = 0;
$dealQuery->domainId = 1;               // amazon.com
$dealQuery->priceTypes = [0];           // AMAZON price type
$dealQuery->dateRange = 1;              // interval: last week
$dealQuery->isRangeEnabled = true;
$dealQuery->currentRange = [500, 40000];
$dealQuery->deltaPercentRange = [20, 100];
$dealQuery->sortType = 4;
$response = $api->sendRequestWithRetry(Request::getDealsRequest($dealQuery));
if ($response->status == ResponseStatus::OK) {
    foreach ($response->deals->dr as $deal) {
        echo $deal->asin . "  " . $deal->title . PHP_EOL;
    }
}

import requests

query = {
    "page": 0,
    "domainId": 1,
    "priceTypes": [0],
    "dateRange": 1,
    "isRangeEnabled": True,
    "currentRange": [500, 40000],
    "deltaPercentRange": [20, 100],
    "sortType": 4,
}
r = requests.post("https://api.keepa.com/deal",
                  params={"key": "YOUR_API_KEY"}, json=query)
data = r.json()
for deal in data["deals"]["dr"]:
    print(deal["asin"], deal["title"])

const query = {
  page: 0,
  domainId: 1,
  priceTypes: [0],
  dateRange: 1,
  isRangeEnabled: true,
  currentRange: [500, 40000],
  deltaPercentRange: [20, 100],
  sortType: 4
};

const res = await fetch("https://api.keepa.com/deal?key=YOUR_API_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(query)
});
const data = await res.json();
for (const deal of data.deals.dr) console.log(deal.asin, deal.title);

curl -s -X POST "https://api.keepa.com/deal?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":0,"domainId":1,"priceTypes":[0],"dateRange":1,"isRangeEnabled":true,"currentRange":[500,40000],"deltaPercentRange":[20,100],"sortType":4}'

Paging through all results#

Iterate page starting at 0, keeping all other parameters identical, and stop once a response contains fewer than 150 deals (5 tokens per request, up to 10,000 ASINs in total):

page = 0
all_deals = []
while True:
    query["page"] = page
    r = requests.post("https://api.keepa.com/deal",
                      params={"key": "YOUR_API_KEY"}, json=query)
    dr = r.json()["deals"]["dr"]
    all_deals.extend(dr)
    if len(dr) < 150:
        break  # last page reached
    page += 1

Example response#

{
  "timestamp": 1753651260000,
  "tokensLeft": 55,
  "refillIn": 42000,
  "refillRate": 5,
  "tokenFlowReduction": 0,
  "tokensConsumed": 5,
  "processingTimeInMs": 91,
  "deals": {
    "dr": [
      {
        "asin": "B0F3GWXLTS",
        "title": "Stainless Steel Insulated Water Bottle, 32 oz",
        "creationDate": 7663480,
        "categories": [16310101, 2251595011],
        "rootCat": 16310101,
        "current": [1999, 2499, -1, 4123],
        "currentSince": [7663480, 7660110, -1, 7663465],
        "delta": [[500, 350, -1, 1200], [780, 410, -1, 2050]],
        "deltaPercent": [[20, 12, -1, 23], [28, 14, -1, 33]],
        "deltaLast": [-500, 0, -1, 0],
        "avg": [[2499, 2849, -1, 5323], [2779, 2910, -1, 6173]],
        "lastUpdate": 7663510,
        "lightningEnd": 0,
        "image": [54, 49, 107, 51, 76, 97, 121, 55, 74, 85, 76, 46, 106, 112, 103]
      }
    ],
    "categoryIds": [16310101, 165793011],
    "categoryNames": ["Grocery & Gourmet Food", "Toys & Games"],
    "categoryCount": [97, 40]
  }
}

Response shortened for readability; illustrative values. Prices are integers in the smallest currency unit (e.g. 1999 = $19.99), timestamps like creationDate are in Keepa Time minutes, and image is an array of US-ASCII character codes (here decoding to 61k3Lay7JUL.jpg). See the Deal Object page for the full structure of the entries in dr.