# Product Finder

Source: https://env.7xmtools.com/api-docs/product-finder.html

Search for products in the Keepa database that match your specified criteria and receive a Search Insights summary that aggregates KPIs (prices, seller mix, brand counts, etc.) across the entire result set. You can search and sort by nearly all product fields.

GET / POST · 10 + 1 per 100 ASINs

This request offers the same core functionality as the [Product Finder](https://env.7xmtools.com/finder) on the Keepa website.

- The request returns only ASIN lists, not [product objects](https://env.7xmtools.com/api-docs/product-object.html).
- Each request consumes 10 tokens plus an additional token per 100 ASINs in the result set.
- A query can return up to 10,000 ASINs using paging, with a minimum page size of 50 ASINs. If using paging, initial search results are not cached, so the order of results may be inconsistent between individual pages if there is a delay between consecutive page requests.
- Filters are joined by an **AND** condition.
- For filters allowing multiple entries (all arrays), each specified entry is considered with an **OR** condition, supporting a maximum of 50 entries.
- The product query searches the Keepa database, not Amazon's. It may not find all products on Amazon that match your query.
- Product data constantly changes. Running the same query twice may yield different results, as products may be misplaced due to recent changes or updates during the query execution.

> **Note:** All API requests execute regardless of your current token balance, as long as it's positive. Requesting large result sets may cause your token balance to go negative. Use with caution!

## Endpoint

You can choose between an HTTP GET or POST request.

### GET format

```
GET https://api.keepa.com/query?key=<yourAccessKey>&domain=<domainId>&selection=<queryJSON>[&stats=1]
```

The `<queryJSON>` must be **URL-encoded** if the GET format is used.

### POST format

```
POST https://api.keepa.com/query?domain=<domainId>&key=<yourAccessKey>[&stats=1]
```

The POST payload must contain the `<queryJSON>`.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `key` | required | Your private API key. |
| `domain` | required | Integer value for the Amazon locale you want to access. See the [valid domain IDs](https://env.7xmtools.com/api-docs/product-finder.html#domain-ids) below. |
| `selection` | required | The query JSON containing all request parameters (see [below](https://env.7xmtools.com/api-docs/product-finder.html#the-query-json)). URL-encoded as GET parameter, or sent as the POST body. |
| `stats` | optional | **Token cost:** 30 tokens + 1 token for every 1,000,000 products returned by the *query as a whole* (not just the current page). If specified and set to `1`, the response will include a [Search Insights Object](https://env.7xmtools.com/api-docs/search-insights-object.html). Example: `&stats=1` |

### Valid domain IDs

| Domain ID | Locale |
| --- | --- |
| **1** | com |
| **2** | co.uk |
| **3** | de |
| **4** | fr |
| **5** | co.jp |
| **6** | ca |
| **8** | it |
| **9** | es |
| **10** | in |
| **11** | com.mx |
| **12** | com.br |

## Token Cost

- **Base cost:** 10 tokens per request + 1 token per 100 ASINs in the result set.
- **`stats=1`:** additionally 30 tokens + 1 token for every 1,000,000 products matched by the query as a whole (not just the current page).

> **Important:** Requesting large lists may consume more tokens than are available in your bucket, causing your balance to go negative. Use with caution.

## The query JSON

The `selection` JSON combines paging, sorting and filters. All filters are optional; the query is valid as long as at least one filter is specified. The scalar and array filters are listed individually below; price/value statistics filters follow systematic naming patterns of the form `<family>_<PRICE_TYPE>_lte|_gte` (see [price-type statistics filters](https://env.7xmtools.com/api-docs/product-finder.html#price-type-stat-filters)).

```json
{
    "page": Integer,
    "perPage": Integer,
    "sort": [ [String, String] ],

    "rootCategory": Long[],
    "categories_include": Long[],
    "categories_exclude": Long[],
    "salesRankReference": Long,
    "title": String,
    "manufacturer": String[],
    "brand": String[],
    "singleVariation": Boolean,
    "historicalParentASIN": String,
    "hasParentASIN": Boolean,
    "productType": Integer,
    "availabilityAmazon": Integer[],
    "returnRate": Integer[],
    "hasReviews": Boolean,
    "isLowestOffer": Boolean,
    "trackingSince_lte": Integer, "trackingSince_gte": Integer,
    "lastPriceChange_lte": Integer, "lastPriceChange_gte": Integer,
    "lastOffersUpdate_lte": Integer, "lastOffersUpdate_gte": Integer,

    "partNumber": String[], "model": String[],
    "color": String[], "size": String[], "edition": String[], "format": String[],
    "author": String[], "binding": String[], "genre": String[], "languages": String[],
    "publisher": String[], "platform": String[],
    "activeIngredients": String[], "specialIngredients": String[],
    "itemTypeKeyword": String[], "targetAudienceKeyword": String[],
    "itemForm": String[], "scent": String[], "unitType": String[],
    "pattern": String[], "style": String[], "material": String[],
    "brandStoreName": String[], "brandStoreUrlName": String[],
    "frequentlyBoughtTogether": String[],

    "packageHeight_lte": Integer, "packageHeight_gte": Integer,
    "packageLength_lte": Integer, "packageLength_gte": Integer,
    "packageWidth_lte": Integer, "packageWidth_gte": Integer,
    "packageWeight_lte": Integer, "packageWeight_gte": Integer,
    "itemHeight_lte": Integer, "itemHeight_gte": Integer,
    "itemLength_lte": Integer, "itemLength_gte": Integer,
    "itemWidth_lte": Integer, "itemWidth_gte": Integer,
    "itemWeight_lte": Integer, "itemWeight_gte": Integer,

    "variationCount_lte": Integer, "variationCount_gte": Integer,
    "imageCount_lte": Integer, "imageCount_gte": Integer,
    "videoCount_lte": Byte, "videoCount_gte": Byte,
    "variationReviewCount_lte": Integer, "variationReviewCount_gte": Integer,
    "variationRatingCount_lte": Integer, "variationRatingCount_gte": Integer,

    "buyBoxStatsAmazon30_lte": Integer, "buyBoxStatsAmazon30_gte": Integer,
    "buyBoxStatsAmazon90_lte": Integer, "buyBoxStatsAmazon90_gte": Integer,
    "buyBoxStatsAmazon180_lte": Integer, "buyBoxStatsAmazon180_gte": Integer,
    "buyBoxStatsAmazon365_lte": Integer, "buyBoxStatsAmazon365_gte": Integer,
    "buyBoxStatsTopSeller30_lte": Integer, "buyBoxStatsTopSeller30_gte": Integer,
    "buyBoxStatsTopSeller90_lte": Integer, "buyBoxStatsTopSeller90_gte": Integer,
    "buyBoxStatsTopSeller180_lte": Integer, "buyBoxStatsTopSeller180_gte": Integer,
    "buyBoxStatsTopSeller365_lte": Integer, "buyBoxStatsTopSeller365_gte": Integer,
    "buyBoxStatsSellerCount30_lte": Integer, "buyBoxStatsSellerCount30_gte": Integer,
    "buyBoxStatsSellerCount90_lte": Integer, "buyBoxStatsSellerCount90_gte": Integer,
    "buyBoxStatsSellerCount180_lte": Integer, "buyBoxStatsSellerCount180_gte": Integer,
    "buyBoxStatsSellerCount365_lte": Integer, "buyBoxStatsSellerCount365_gte": Integer,

    "outOfStockPercentage90_lte": Integer, "outOfStockPercentage90_gte": Integer,
    "outOfStockCountAmazon30_lte": Integer, "outOfStockCountAmazon30_gte": Integer,
    "outOfStockCountAmazon90_lte": Integer, "outOfStockCountAmazon90_gte": Integer,
    "deltaPercent90_monthlySold_lte": Integer, "deltaPercent90_monthlySold_gte": Integer,
    "monthlySold_lte": Integer, "monthlySold_gte": Integer,

    "couponOneTimeAbsolute_lte": Integer, "couponOneTimeAbsolute_gte": Integer,
    "couponOneTimePercent_lte": Integer, "couponOneTimePercent_gte": Integer,
    "couponSNSPercent_lte": Integer, "couponSNSPercent_gte": Integer,
    "flipability30_lte": Byte, "flipability30_gte": Byte,
    "flipability90_lte": Byte, "flipability90_gte": Byte,
    "flipability365_lte": Byte, "flipability365_gte": Byte,
    "businessDiscount_lte": Byte, "businessDiscount_gte": Byte,

    "isHazMat": Boolean, "isHeatSensitive": Boolean, "isAdultProduct": Boolean,
    "isEligibleForSuperSaverShipping": Boolean,
    "isSNS": Boolean, "isMerchOnDemand": Boolean, "isPrimeExclusive": Boolean,
    "batteriesRequired": Boolean, "batteriesIncluded": Boolean,
    "hasMainVideo": Boolean, "hasAPlus": Boolean, "hasAPlusFromManufacturer": Boolean,

    "buyBoxIsAmazon": Boolean, "buyBoxIsFBA": Boolean, "buyBoxIsUnqualified": Boolean,
    "buyBoxIsPreorder": Boolean, "buyBoxIsBackorder": Boolean, "buyBoxIsPrimeExclusive": Boolean,
    "buyBoxSellerId": String[], "buyBoxUsedCondition": Integer[],
    "buyBoxUsedIsFBA": Boolean, "buyBoxUsedSellerId": String[],
    "sellerIds": String[], "sellerIdsLowestFBA": String[], "sellerIdsLowestFBM": String[],
    "dealType": String[],

    "numberOfItems_lte": Integer, "numberOfItems_gte": Integer,
    "numberOfPages_lte": Integer, "numberOfPages_gte": Integer,
    "publicationDate_lte": Integer, "publicationDate_gte": Integer,
    "releaseDate_lte": Integer, "releaseDate_gte": Integer,
    "lightningEnd_lte": Integer, "lightningEnd_gte": Integer,

    "current_<PRICE_TYPE>_lte": Integer, "current_<PRICE_TYPE>_gte": Integer,
    "delta30_<PRICE_TYPE>_lte": Integer, "delta30_<PRICE_TYPE>_gte": Integer,
    "delta90_<PRICE_TYPE>_lte": Integer, "delta90_<PRICE_TYPE>_gte": Integer,
    "deltaPercent30_<PRICE_TYPE>_lte": Integer, "deltaPercent30_<PRICE_TYPE>_gte": Integer,
    "deltaPercent90_<PRICE_TYPE>_lte": Integer, "deltaPercent90_<PRICE_TYPE>_gte": Integer,
    "deltaLast_<PRICE_TYPE>_lte": Integer, "deltaLast_<PRICE_TYPE>_gte": Integer,
    "avg30_<PRICE_TYPE>_lte": Integer, "avg30_<PRICE_TYPE>_gte": Integer,
    "avg90_<PRICE_TYPE>_lte": Integer, "avg90_<PRICE_TYPE>_gte": Integer,
    "avg180_<PRICE_TYPE>_lte": Integer, "avg180_<PRICE_TYPE>_gte": Integer,
    "avg365_<PRICE_TYPE>_lte": Integer, "avg365_<PRICE_TYPE>_gte": Integer,
    "lastPriceChange_<PRICE_TYPE>_lte": Integer, "lastPriceChange_<PRICE_TYPE>_gte": Integer,
    "backInStock_<PRICE_TYPE>": Boolean,
    "isLowest_<PRICE_TYPE>": Boolean,
    "isLowest90_<PRICE_TYPE>": Boolean
}
```

> **Note:** `isLowestOffer` (Boolean) only includes products for which the selected price type is the lowest of all New offers (applicable to Amazon and Marketplace New). Example: `"isLowestOffer": true`

### Paging

*Paging is optional; by default, up to 50 results are provided.*

| Field | Description |
| --- | --- |
| `page` | Most queries have more than 50 results (the minimum page size). To retrieve additional results, iterate the `page` parameter while keeping all other parameters identical. Start with `page` 0 and stop when the response contains fewer than 50 results. Each response also includes the `totalResults` field, indicating the number of matched products. When requesting a `page` other than 0, the combination of `page` and `perPage` must not exceed 10,000 results. Example: `0` |
| `perPage` | Specifies the number of results to retrieve per page. The default and minimum values are 50 ASINs. If `page` is **0**, `perPage` can be as large as 10,000. If a `page` other than 0 is requested, the combination of `page` and `perPage` must not exceed 10,000 results. |

### Sorting

*Sorting is optional; by default, results are sorted ascending by current sales rank.*

`sort` can include up to three sorting criteria. Use a two-dimensional array where each entry is in the format `[fieldName, sortDirection]`:

- **fieldName**: any filter from the list below that is either a String or Integer, except the filter-only fields listed in the note. The `fieldName` must not include `_lte` or `_gte`.
- **sortDirection**: use `"asc"` for ascending or `"desc"` for descending.

```json
"sort": [ ["current_SALES", "asc"] ]
```

> **Note:** a few filters can be matched on but not sorted by: `partNumber`, `historicalSellerIds`, `sellerIdsFBA`, `sellerIdsFBM`, `buyBoxStatsTopSellerId30`, `buyBoxStatsTopSellerId90`, `buyBoxStatsTopSellerId180` and `buyBoxStatsTopSellerId365`. Naming one in `sort` does **not** produce an error — the whole `sort` is discarded and the default sort applies instead, the same way an unrecognised field name does.

### Filter basics

The following fields act as filters. Only products that **exactly** match all filters will be returned by the query. All string filters are case insensitive and can be used as exclusion filters by using the prefix `✜`. Filters ending in `_gte` restrict the output to values "Greater than or equal" to the specified value, while `_lte` means "Less than or equal".

#### minMatch — K-of-N matching on array filters

Entries within one array filter are normally joined by **OR**: any one of them may match. `minMatch` raises that bar per field, as a map of filter name to the number of entries that must match. Setting it equal to the number of entries turns that filter into an **AND**.

```json
"minMatch": { "sellerIds": 2, "manufacturer": 1 }
```

Here a product must be offered by at least two of the listed `sellerIds`, while `manufacturer` keeps its default OR behaviour. Values are clamped to the number of entries actually supplied for that filter.

#### exists — matching on a missing value

Every other filter matches on a value being *present*. `exists` is the opposite: a map of filter name to a Boolean, where `false` selects the products we hold no value for, and `true` those we do.

```json
"exists": { "brand": false, "color": true }
```

This example returns products that have no brand and do have a colour. Entries combine with every other filter using AND, so `"brand": ["canon"]` together with `"exists": { "brand": false }` matches nothing.

An unknown or unsupported filter name is rejected with an `invalidParameter` error rather than ignored, and at most 50 entries are accepted. Filters that always carry a value — `productType` or `hasParentASIN`, for example — are not supported, because asking whether they exist has no meaningful answer. Supported filter names:

| Group | Filters |
| --- | --- |
| Product attributes | `activeIngredients`, `author`, `binding`, `brand`, `brandStoreName`, `brandStoreUrlName`, `color`, `dealType`, `edition`, `format`, `itemForm`, `itemTypeKeyword`, `languages`, `manufacturer`, `material`, `model`, `partNumber`, `pattern`, `scent`, `size`, `specialIngredients`, `style`, `targetAudienceKeyword`, `type`, `unitType` |
| Classification | `categories`, `salesRankDisplayGroup`, `websiteDisplayGroup`, `websiteDisplayGroupName` |
| Dimensions & packaging | `itemHeight`, `itemLength`, `itemWeight`, `itemWidth`, `numberOfItems`, `numberOfPages`, `packageHeight`, `packageLength`, `packageQuantity`, `packageWeight`, `packageWidth` |
| Sales, fees & coupons | `businessDiscount`, `couponOneTimeAbsolute`, `couponOneTimePercent`, `couponSNSPercent`, `deltaPercent90_monthlySold`, `fbaFees`, `monthlySold`, `monthlySoldPeak`, `returnRate` |
| Buy Box statistics | `buyBoxShippingCountry`, `buyBoxStandardDeviation30`, `buyBoxStandardDeviation90`, `buyBoxStandardDeviation365`, `buyBoxStatsTopSellerId30`, `buyBoxStatsTopSellerId90`, `buyBoxStatsTopSellerId180`, `buyBoxStatsTopSellerId365`, `flipability30`, `flipability90`, `flipability365` |
| Sellers | `historicalSellerIds`, `sellerIds`, `sellerIdsFBA`, `sellerIdsFBM`, `sellerIdsLowestFBA`, `sellerIdsLowestFBM` |
| Dates | `listedSince`, `publicationDate`, `releaseDate` |

> **Note:** for the numeric filters, missing is not the same as zero. `"monthlySold_gte": 0` with `"monthlySold_lte": 0` matches products whose value is missing *or* zero; `"exists": { "monthlySold": false }` matches only those where it is missing.

### Category & title filters

| Filter | Description |
| --- | --- |
| `rootCategory` | Only include products listed in these root-categories. Array with up to 50 [category node ids](https://env.7xmtools.com/api-docs/category-object.html). Example: `[562066]` |
| `categories_include` | Only include products listed directly in these sub-categories. Array with up to 50 [category node ids](https://env.7xmtools.com/api-docs/category-object.html). Example: `[3010075031, 12950651, 355007011]` |
| `categories_exclude` | Exclude products listed directly in these sub-categories. Array with up to 50 [category node ids](https://env.7xmtools.com/api-docs/category-object.html). Example: `[77028031, 186606]` |
| `salesRankReference` | [Category node id](https://env.7xmtools.com/api-docs/category-object.html) of the product's salesRankReference category. Example: `562066` |
| `title` | Title of the product. Works on a keyword basis, meaning the product's title must contain the specified string's keywords, separated by white space. Supports up to 50 keywords. The search is case-insensitive. Partial keyword matches are not supported. Examples:<br>• *Digital Camera Canon*: title must contain all three keywords, in any order or position.<br>• *"Digital Camera" Canon*: title must contain the keyword *Digital Camera* and *Canon*.<br>• *-digital camera*: title must *not* contain the keyword *digital* and must contain *camera*. |

### Product type, variations & state

| Filter | Description |
| --- | --- |
| `productType` | Determines what data is available for the product. Possible filter values:<br>• **0** — STANDARD: everything accessible<br>• **1** — DOWNLOADABLE: no marketplace/3rd party price data<br>• **2** — EBOOK: no marketplace offers data<br>• **5** — VARIATION\_PARENT: product is a parent ASIN. Only sales rank and `variations` is set. |
| `singleVariation` | If set to `true`, only one variation of a product will be returned. |
| `historicalParentASIN` | Find historical children ASINs (variations) for any parent ASIN. Example: `B0FJZJ82ZG` |
| `hasParentASIN` | Whether or not the product has a parent ASIN. |
| `availabilityAmazon` | Availability of the Amazon offer. Possible values:<br>• **-1**: no Amazon offer exists<br>• **0**: Amazon offer is in stock and shippable<br>• **1**: Amazon offer is currently not in stock, but will be in the future (pre-order)<br>• **2**: Amazon offer availability is "unknown"<br>• **3**: Amazon offer is currently not in stock, but will be in the future (back-order)<br>• **4**: Amazon offer shipping is delayed — see the product's `availabilityAmazonDelay` for more details |
| `returnRate` | The customer return rate for a product. Possible values:<br>• **1**: the product has a low return rate<br>• **2**: the product has a high return rate |
| `hasReviews` | Whether or not the product has reviews. |
| `trackingSince_lte` / `_gte` | Indicates the time Keepa started tracking this product, in [Keepa Time minutes](https://env.7xmtools.com/api-docs/product-finder.html#keepa-time-minutes). Example: `3411319` |
| `lastPriceChange_lte` / `_gte` | The last time a price change (any price type) was registered, in [Keepa Time minutes](https://env.7xmtools.com/api-docs/product-finder.html#keepa-time-minutes). |
| `lastOffersUpdate_lte` / `_gte` | The time when the offers were last updated (see the [product request's](https://env.7xmtools.com/api-docs/product.html) offers parameter), in [Keepa Time minutes](https://env.7xmtools.com/api-docs/product-finder.html#keepa-time-minutes). Can be used to retrieve only products with fresh offers-related data. Example: `3411319` |
| `monthlySold_lte` / `_gte` | How often this product was bought in the past month. This field represents the *bought past month* metric found on Amazon search result pages. It is not an estimate. *Undefined* if it has no value. Most ASINs do not have this value set. The value is variation specific. Example: `1000` — the ASIN was bought at least 1000 times in the past month. |
| `deltaPercent90_monthlySold_lte` / `_gte` | Percentage change in monthly sales over the last 90 days. Examples: max `15`, min `-10` |

### Product attribute filters (String arrays)

Most of these are also available to the [`exists`](https://env.7xmtools.com/api-docs/product-finder.html#exists-filter) filter, to find the products that carry no value for one of them at all.

| Filter | Description / Example |
| --- | --- |
| `manufacturer` | Names of manufacturers. Example: *Canon* |
| `brand` | Names of brands. Example: *Canon* |
| `partNumber` | Names of part numbers. Example: *DSC-H300/BM-RB* |
| `model` | Names of models. Example: *2016* |
| `color` | Names of colors. Example: *black* |
| `size` | Names of sizes. Example: *large* |
| `edition` | Names of editions. Example: *first edition* |
| `format` | Names of formats. Example: *cd-rom* |
| `author` | Names of authors. Example: *anonymous* |
| `binding` | Names of bindings. Example: *paperback* |
| `genre` | Names of genres. Example: *horror* |
| `languages` | Languages available for the item. Example: *english* |
| `publisher` | Publisher of the item. Example: *penguin books* |
| `platform` | Platforms the item is available on. Example: *windows* |
| `activeIngredients` | Active ingredients in the product. Example: *aloe* |
| `specialIngredients` | Special or additional ingredients in the product. Example: *fragrance-free* |
| `itemTypeKeyword` | Keywords describing the type of item. Example: *road-running-shoes* |
| `targetAudienceKeyword` | Keywords indicating the target audience. Example: *dogs* |
| `itemForm` | The form of the item. Example: *liquid* |
| `scent` | Scent of the product, if applicable. Example: *lavender* |
| `unitType` | Type of unit measurement used. Example: *count* |
| `pattern` | Pattern design of the item. Example: *striped* |
| `style` | Style or design aesthetic of the item. Example: *modern* |
| `material` | Material composition of the item. Example: *cotton* |
| `brandStoreName` | Name of the brand's store. Example: `["techworld"]` |
| `brandStoreUrlName` | URL-friendly name of the brand's store. Example: `["techworld-store"]` |
| `frequentlyBoughtTogether` | Specify an ASIN to retrieve products that are often bought together with it. Example: *B06XFTZGV5* |

### Dimensions & media

| Filter | Description |
| --- | --- |
| `packageHeight` / `packageLength` / `packageWidth` `[_lte, _gte]` | The package's height/length/width in millimeters. Example: `144` |
| `packageWeight` `[_lte, _gte]` | The package's weight in grams. Example: `1500` (= 1.5 kg) |
| `itemHeight` / `itemLength` / `itemWidth` `[_lte, _gte]` | The item's height/length/width in millimeters. Example: `144` |
| `itemWeight` `[_lte, _gte]` | The item's weight in grams. Example: `1500` (= 1.5 kg) |
| `variationCount` `[_lte, _gte]` | The number of variations of this product. Example: `1` |
| `imageCount` `[_lte, _gte]` | The number of images of this product. Example: `1` |
| `videoCount` `[_lte, _gte]` | Number of videos associated with the item. Examples: max `10`, min `1` |
| `hasMainVideo` | If the item has a main promotional video, which is part of the product image carousel. Example: `true` |
| `hasAPlus` | If the item has A+ content. Example: `false` |
| `hasAPlusFromManufacturer` | If the A+ content is provided by the manufacturer or vendor. Example: `true` |
| `numberOfItems` `[_lte, _gte]` | The number of items of this product. Example: `1` |
| `numberOfPages` `[_lte, _gte]` | The number of pages of this product. Example: `514` |
| `publicationDate` `[_lte, _gte]` | The item's publication date, in [Keepa Time minutes](https://env.7xmtools.com/api-docs/product-finder.html#keepa-time-minutes). Example: `3411319` |
| `releaseDate` `[_lte, _gte]` | The item's release date, in [Keepa Time minutes](https://env.7xmtools.com/api-docs/product-finder.html#keepa-time-minutes). Example: `3411319` |
| `variationReviewCount` `[_lte, _gte]` | Number of reviews specific to a variation. Examples: max `100`, min `10` |
| `variationRatingCount` `[_lte, _gte]` | Number of ratings specific to a variation. Examples: max `200`, min `20` |

### Product flags (Boolean)

| Filter | Description |
| --- | --- |
| `isHazMat` | Indicates whether the product is classified as hazardous material (HazMat). Example: `true` |
| `isHeatSensitive` | Indicates whether the product is classified as heat sensitive (e.g. meltable). Example: `true` |
| `isAdultProduct` | Indicates if the item is considered to be for adults only. Example: `true` |
| `isEligibleForSuperSaverShipping` | Whether or not the product is eligible for super saver shipping by Amazon. Example: `true` |
| `isSNS` | If the product's Buy Box is available for [subscribe and save](https://www.amazon.com/b?node=5856181011). Example: `true` |
| `isMerchOnDemand` | If the product is a MerchOnDemand. Example: `true` |
| `isPrimeExclusive` | A Prime exclusive offer can only be ordered if the buyer has an active Prime subscription. Example: `true` |
| `batteriesRequired` | If the item requires batteries. Example: `true` |
| `batteriesIncluded` | If batteries are included with the item. Example: `false` |

### Buy Box & seller filters

| Filter | Description |
| --- | --- |
| `buyBoxIsAmazon` | If the Buy Box is held by Amazon. Example: `true` |
| `buyBoxIsFBA` | If the Buy Box is fulfilled by Amazon (FBA). Example: `false` |
| `buyBoxIsUnqualified` | If the Buy Box is unqualified. Example: `false` |
| `buyBoxIsPreorder` | If the product's Buy Box is a preorder. Example: `true` |
| `buyBoxIsBackorder` | If the product's Buy Box is backordered. Example: `true` |
| `buyBoxIsPrimeExclusive` | If the product's Buy Box is prime exclusive. Example: `true` |
| `buyBoxSellerId` | Seller IDs in the Buy Box. Example: `["ATVPDKIKX0DER"]` |
| `buyBoxUsedCondition` | The offer sub-condition of the **used** Buy Box. Example: `[2, 3]`<br>ValueCondition 2Used - Like New 3Used - Very Good 4Used - Good 5Used - Acceptable |
| `buyBoxUsedIsFBA` | If the Used Buy Box is fulfilled by Amazon. Example: `true` |
| `buyBoxUsedSellerId` | Seller IDs for used items eligible for the Buy Box. Example: `["ATVPDKIKX0DER"]` |
| `sellerIds` | List of seller IDs offering the item. Example: `["ATVPDKIKX0DER"]` |
| `sellerIdsLowestFBA` | Seller IDs offering the lowest price via FBA. Example: `["ATVPDKIKX0DER"]` |
| `sellerIdsLowestFBM` | Seller IDs offering the lowest price via FBM. Example: `["ATVPDKIKX0DER"]` |
| `dealType` | The type of the deal badge. Valid values: `PRIME_DAY`, `PRIME_DAY_EARLY`, `EARLY_ACCESS_WITH_PRIME`, `PRIME_EXCLUSIVE`, `SELLING_FAST`, `PRIME_SELLING_FAST`, `LIMITED_TIME_DEAL`, `COUNTDOWN_ENDS_IN`, `APP_ONLY`, `CLEARANCE_NO_RETURNS`, `SPECIAL_EVENT_SALE`, `GENERIC_OFFER_PROMO`, `UNKNOWN`. Example: `["LIMITED_TIME_DEAL"]` |
| `buyBoxStatsAmazon` `[30, 90, 180, 365]` `[_lte, _gte]` | The percentage the Amazon offer held the Buy Box in the given interval. Example: `30` |
| `buyBoxStatsTopSeller` `[30, 90, 180, 365]` `[_lte, _gte]` | Buy Box Share % of the seller with highest % won (Amazon included). Example: `30` |
| `buyBoxStatsSellerCount` `[30, 90, 180, 365]` `[_lte, _gte]` | Number of sellers with Buy Box ownership in the interval. Example: `2` |

### Stock, coupons & scores

| Filter | Description |
| --- | --- |
| `outOfStockPercentage90` `[_lte, _gte]` | 90-day Amazon out-of-stock percentage. Examples: `0` = never out of stock, `100` = out of stock 100% of the time, `25` = out of stock 25% of the time. A per-price-type form also exists for four types: `outOfStockPercentage90_BB`, `outOfStockPercentage90_BB_USED`, `outOfStockPercentage90_NEW` and `outOfStockPercentage90_USED`, each with `_lte` / `_gte`. |
| `outOfStockCountAmazon30` `[_lte, _gte]` | Number of times the item was out of stock on Amazon in the last 30 days. Examples: max `2`, min `1` |
| `outOfStockCountAmazon90` `[_lte, _gte]` | Number of times the item was out of stock on Amazon in the last 90 days. Examples: max `5`, min `3` |
| `couponOneTimeAbsolute` `[_lte, _gte]` | Absolute value for one-time coupons. Examples: max `50`, min `10` |
| `couponOneTimePercent` `[_lte, _gte]` | Percentage value for one-time coupons. Examples: max `20`, min `5` |
| `couponSNSPercent` `[_lte, _gte]` | Percentage value for SNS (Subscribe & Save) coupons. Examples: max `15`, min `3` |
| `flipability30` / `flipability90` / `flipability365` `[_lte, _gte]` | Flipability score over 30 / 90 / 365 days. Examples: `flipability30` max `80`, min `20`; `flipability90` max `85`, min `25`; `flipability365` max `90`, min `30` |
| `businessDiscount` `[_lte, _gte]` | Business discount available. Examples: max `15`, min `5` |
| `lightningEnd` `[_lte, _gte]` | Find current and upcoming lightning deals that end within the defined range. In [Keepa Time minutes](https://env.7xmtools.com/api-docs/product-finder.html#keepa-time-minutes). |

### Update & lifecycle times

All values are [Keepa Time minutes](https://env.7xmtools.com/api-docs/product-finder.html#keepa-time-minutes).

| Filter | Description |
| --- | --- |
| `lastUpdate` `[_lte, _gte]` | When Keepa last updated the product. If you do not specify this filter, the query is automatically limited to products updated within the last 6 months. |
| `listedSince` `[_lte, _gte]` | When the product was first listed on Amazon, as far as Keepa can determine it. |
| `lastRatingUpdate` `[_lte, _gte]` | When the rating and review count were last updated. |
| `lastBusinessDiscountUpdate` `[_lte, _gte]` | When the business discount was last updated. |
| `lightningStart` `[_lte, _gte]` | Start of the product’s Lightning Deal. Pairs with the documented `lightningEnd`. |
| `numberOfTrackings` `[_lte, _gte]` | How many Keepa users track this product — a rough popularity signal. |

### Sales rank filters

| Filter | Description |
| --- | --- |
| `salesRankDrops30` `[_lte, _gte]` | Number of sales rank drops in the last 30 days. |
| `salesRankDrops90` `[_lte, _gte]` | Number of sales rank drops in the last 90 days. |
| `salesRankDrops180` `[_lte, _gte]` | Number of sales rank drops in the last 180 days. |
| `salesRankDrops365` `[_lte, _gte]` | Number of sales rank drops in the last 365 days. |
| `salesRankDisplayGroup` | String array. The sales rank display group the product belongs to. Example: `["fashion_display_on_website"]` |
| `srAvg<C><MM>` `[_lte, _gte]` | Average sales rank during one specific past month, for the rolling last 36 months. `<C>` is the year modulo 3 (`0`–`2`) and `<MM>` is the zero-based month (`00` = January … `11` = December) — e.g. `srAvg003` is April of the year whose number is divisible by 3. Same encoding the [Best Sellers](https://env.7xmtools.com/api-docs/best-sellers.html) request uses for historical lists. |

### Offer counts & Buy Box statistics

| Filter | Description |
| --- | --- |
| `totalOfferCount` `[_lte, _gte]` | Total number of marketplace offers. |
| `offerCountFBA` `[_lte, _gte]` | Number of FBA offers. |
| `offerCountFBM` `[_lte, _gte]` | Number of FBM offers. |
| `buyBoxEligibleOfferCountsNewFBA` `[_lte, _gte]` | Buy Box eligible New FBA offer count. |
| `buyBoxEligibleOfferCountsNewFBM` `[_lte, _gte]` | Buy Box eligible New FBM offer count. |
| `buyBoxEligibleOfferCountsUsedFBA` `[_lte, _gte]` | Buy Box eligible Used FBA offer count. |
| `buyBoxEligibleOfferCountsUsedFBM` `[_lte, _gte]` | Buy Box eligible Used FBM offer count. |
| `buyBoxStandardDeviation30` `[_lte, _gte]` | Standard deviation of the Buy Box price over the last 30 days. |
| `buyBoxStandardDeviation90` `[_lte, _gte]` | Standard deviation of the Buy Box price over the last 90 days. |
| `buyBoxStandardDeviation365` `[_lte, _gte]` | Standard deviation of the Buy Box price over the last 365 days. |
| `BUY_BOX_SHIPPING_shipping` `[_lte, _gte]` | Shipping cost of the Buy Box offer, as an integer of the locale’s smallest currency unit. |
| `buyBoxIsPrimeEligible` | Boolean. Whether the Buy Box offer is Prime eligible. |
| `buyBoxShippingCountry` | String array. Default shipping country of the Buy Box seller. Example: `["US"]` |
| `buyBoxStatsTopSellerId30` | String array. Seller IDs that held the Buy Box most often in the last 30 days. |
| `buyBoxStatsTopSellerId90` | String array. As above, for the last 90 days. |
| `buyBoxStatsTopSellerId180` | String array. As above, for the last 180 days. |
| `buyBoxStatsTopSellerId365` | String array. As above, for the last 365 days. |
| `sellerIdsFBA` | String array. Seller IDs currently offering the product via FBA. |
| `sellerIdsFBM` | String array. Seller IDs currently offering the product via FBM. |
| `historicalSellerIds` | String array. Seller IDs that have offered the product at any point, not only currently. |
| `isHighestOffer` | Boolean. Whether the selected price is at its highest value. |

### Monthly sold, fees & packaging

| Filter | Description |
| --- | --- |
| `monthlySoldPeak` `[_lte, _gte]` | Highest monthly sold value ever recorded for the product. |
| `monthlySoldPeakDate` `[_lte, _gte]` | When that peak occurred, in [Keepa Time minutes](https://env.7xmtools.com/api-docs/product-finder.html#keepa-time-minutes). |
| `monthlySoldLastKnown` `[_lte, _gte]` | Most recent non-empty monthly sold value. |
| `monthlySoldLastKnownDate` `[_lte, _gte]` | When that value was recorded, in [Keepa Time minutes](https://env.7xmtools.com/api-docs/product-finder.html#keepa-time-minutes). |
| `fbaFees` `[_lte, _gte]` | Total FBA pick & pack fee, as an integer of the locale’s smallest currency unit. |
| `packageQuantity` `[_lte, _gte]` | Number of items in the package. |
| `packageDimension` `[_lte, _gte]` | Combined package dimension, derived from the package length, width and height. |
| `itemDimension` `[_lte, _gte]` | Combined item dimension, derived from the item length, width and height. |

### Classification & state

| Filter | Description |
| --- | --- |
| `type` | String array. Amazon’s product type for the item. Example: `["SHIRT"]` |
| `websiteDisplayGroup` | String array. The product’s website display group. |
| `websiteDisplayGroupName` | String array. The friendlier display group name, and the value the [Best Sellers](https://env.7xmtools.com/api-docs/best-sellers.html) request accepts as a product group. |
| `warehouseCondition` | Integer array. Condition of the cheapest Amazon Warehouse offer: `1` New, `2` Used - Like New, `3` Used - Very Good, `4` Used - Good, `5` Used - Acceptable. |
| `availabilityAmazonMinDelayInDays` `[_lte, _gte]` | Minimum shipping delay in days of the Amazon offer. |
| `outOfStockPercentageInInterval` `[_lte, _gte]` | Out-of-stock percentage over the query’s interval, from `0` to `100`. |
| `isDeal` | Boolean. Whether the product currently qualifies as a deal. |
| `launchpad` | Boolean. Whether the product is part of Amazon Launchpad. |
| `newPriceIsMAP` | Boolean. Whether the New price is hidden on Amazon due to MAP restrictions. |

### Price-type statistics filters

These filter families exist for every price type (see the list below). The placeholder `<PRICE_TYPE>` stands for a price type name such as `AMAZON`, `NEW` or `BUY_BOX_SHIPPING` — e.g. `current_AMAZON_gte`, `avg90_NEW_lte`, `isLowest_BUY_BOX_SHIPPING`.

| Filter family | Description |
| --- | --- |
| `current_<PRICE_TYPE>` `[_lte, _gte]` | Filter for the current price or value. The price is an integer of the respective Amazon locale's smallest currency unit (e.g., euro cents or yen). |
| `delta[1, 7, 30, 90]_<PRICE_TYPE>` `[_lte, _gte]` | Filter for the absolute difference between the current value and the 1, 7, 30 or 90-day average value. The price is an integer of the respective Amazon locale's smallest currency unit. A negative value filters for prices/values that have increased, and a positive value filters for decreased ones. A **0** filters products with no change. |
| `deltaPercent[1, 7, 30, 90]_<PRICE_TYPE>` `[_lte, _gte]` | Filter for the relative difference between the current value and the 1, 7, 30 or 90-day average value. In percentage between 0 and 100%. A positive value filters for prices/values that have decreased, and a negative value filters for increased ones. A **0** filters products with no change. |
| `deltaLast_<PRICE_TYPE>` `[_lte, _gte]` | Filter for the difference between the current value and the previous value. The price is an integer of the respective Amazon locale's smallest currency unit. A positive value filters for prices/values that have decreased, and a negative value filters for increased ones. A **0** filters products with no change. |
| `avg[1, 7, 30, 90, 180, 365]_<PRICE_TYPE>` `[_lte, _gte]` | Filter for the average price or value of the respective last x days. The price is an integer of the respective Amazon locale's smallest currency unit. |
| `lastPriceChange_<PRICE_TYPE>` `[_lte, _gte]` | The last time a price change of this price type was registered, in [Keepa Time minutes](https://env.7xmtools.com/api-docs/product-finder.html#keepa-time-minutes). |
| `backInStock_<PRICE_TYPE>` | Whether or not the price/value was out of stock in the last 60 days and now has an offer again. (Boolean) |
| `isLowest_<PRICE_TYPE>` | Whether or not the current price/value is the lowest ever. (Boolean) |
| `isLowest90_<PRICE_TYPE>` | Whether or not the current price/value is the lowest in the last 90 days. (Boolean) |

#### Available price types

The standard price type set — available in the `current`, `delta`, `deltaPercent`, `deltaLast`, `avg30/90/180` and `backInStock` families:

`AMAZON`, `NEW`, `USED`, `SALES`, `LISTPRICE`, `COLLECTIBLE`, `REFURBISHED`, `NEW_FBM_SHIPPING`, `LIGHTNING_DEAL`, `WAREHOUSE`, `NEW_FBA`, `COUNT_NEW`, `COUNT_USED`, `COUNT_REFURBISHED`, `COUNT_COLLECTIBLE`, `RATING`, `COUNT_REVIEWS`, `BUY_BOX_SHIPPING`, `USED_NEW_SHIPPING`, `USED_VERY_GOOD_SHIPPING`, `USED_GOOD_SHIPPING`, `USED_ACCEPTABLE_SHIPPING`, `REFURBISHED_SHIPPING`, `TRADE_IN`

The `avg365`, `lastPriceChange`, `isLowest` and `isLowest90` families additionally support:

`BUY_BOX_USED_SHIPPING`, `EBAY_NEW_SHIPPING`, `EBAY_USED_SHIPPING`, `PRIME_EXCL`, `RENT`

> **Note:** The price types correspond to the `csv` history types of the [Product Object](https://env.7xmtools.com/api-docs/product-object.html).

## Keepa Time Minutes

Time format used for all timestamps. To convert to an uncompressed Unix epoch time:

- **For milliseconds:** `(keepaTime + 21564000) * 60000`
- **For seconds:** `(keepaTime + 21564000) * 60`

## Response

```json
{
    "asinList": String array,
    "searchInsights": Search Insights Object,
    "totalResults": Integer
}
```

| Field | Description |
| --- | --- |
| `asinList` | Ordered array with the result ASINs. |
| `searchInsights` | Aggregated metrics calculated over matched products: [Search Insights Object](https://env.7xmtools.com/api-docs/search-insights-object.html). Requires the `&stats=1` parameter. |
| `totalResults` | Estimated count of all matched products. |

## Examples

### Example query

Find products in root category `3167641` with a current Amazon price between € 10.00 and € 50.00, 100 results per page:

```json
{
  "rootCategory": 3167641,
  "current_AMAZON_lte": 5000,
  "current_AMAZON_gte": 1000,
  "perPage": 100,
  "page": 0
}
```

> **Tip:** A query can also be built by using the [Product Finder](https://env.7xmtools.com/finder) interface on the Keepa website. The current query can be reviewed by clicking on "Show API query" above the result table.

**Java**

```java
KeepaAPI api = new KeepaAPI("YOUR_API_KEY");
ProductFinderRequest finder = new ProductFinderRequest();
finder.rootCategory = new String[]{"3167641"};
finder.current_AMAZON_gte = 1000;   // prices in cents
finder.current_AMAZON_lte = 5000;
finder.perPage = 100;
finder.page = 0;
api.sendRequest(Request.getProductFinderRequest(AmazonLocale.DE, finder))
    .done(result -> {
        System.out.println(result.asinList.length + " ASINs on this page");
    })
    .fail(failure -> System.out.println(failure));
```

**PHP**

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

use Keepa\objects\ProductFinderRequest;
$api = new KeepaAPI("YOUR_API_KEY");
$finder = new ProductFinderRequest();
$finder->rootCategory = 3167641;
$finder->current_AMAZON_gte = 1000;   // prices in cents
$finder->current_AMAZON_lte = 5000;
$finder->perPage = 100;
$finder->page = 0;
$response = $api->sendRequestWithRetry(Request::getFinderRequest(AmazonLocale::DE, $finder));
if ($response->status == ResponseStatus::OK) {
    print_r($response->asinList);
}
```

**Python**

```python
import requests

selection = {
    "rootCategory": 3167641,
    "current_AMAZON_lte": 5000,
    "current_AMAZON_gte": 1000,
    "perPage": 100,
    "page": 0,
}
r = requests.post(
    "https://api.keepa.com/query",
    params={"domain": 3, "key": "YOUR_API_KEY"},
    json=selection,
)
data = r.json()
print(data["totalResults"], "matches")
print(data["asinList"][:10])
```

**Node.js**

```javascript
const selection = {
  rootCategory: 3167641,
  current_AMAZON_lte: 5000,
  current_AMAZON_gte: 1000,
  perPage: 100,
  page: 0,
};
const res = await fetch("https://api.keepa.com/query?domain=3&key=YOUR_API_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(selection),
});
const data = await res.json();
console.log(data.totalResults, "matches");
console.log(data.asinList.slice(0, 10));
```

**cURL (GET)**

```bash
# GET: the selection JSON must be URL-encoded (--data-urlencode does this)
curl -s -G "https://api.keepa.com/query" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "domain=3" \
  --data-urlencode 'selection={"rootCategory":3167641,"current_AMAZON_lte":5000,"current_AMAZON_gte":1000,"perPage":100,"page":0}'
```

**cURL (POST)**

```bash
# POST: the selection JSON is the request body
curl -s -X POST "https://api.keepa.com/query?domain=3&key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rootCategory":3167641,"current_AMAZON_lte":5000,"current_AMAZON_gte":1000,"perPage":100,"page":0}'
```

### Example with Search Insights (stats=1)

Same query, but with aggregated KPIs over the whole result set — note the additional token cost:

```bash
curl -s -X POST "https://api.keepa.com/query?domain=3&key=YOUR_API_KEY&stats=1" \
  -H "Content-Type: application/json" \
  -d '{"rootCategory":3167641,"current_AMAZON_gte":1000,"deltaPercent90_AMAZON_gte":20,"sort":[["current_SALES","asc"]]}'
```

### Example response

```json
{
  "timestamp": 1783382461000,
  "tokensLeft": 248,
  "refillIn": 31000,
  "refillRate": 5,
  "tokenFlowReduction": 0.0,
  "tokensConsumed": 11,
  "processingTimeInMs": 342,
  "asinList": [
    "B0BDHWDR12",
    "B09XS7JWHH",
    "B08N5WRWNW",
    "B07YN82X3B",
    "B01M0AGIKS"
  ],
  "totalResults": 18234
}
```

*Response shortened for readability; illustrative values.* With `&stats=1` the response additionally contains the `searchInsights` field — see the [Search Insights Object](https://env.7xmtools.com/api-docs/search-insights-object.html) for a full example.