Marketplace Offer Object

The offer object is returned by the Product Request when the optional offers parameter is used, and it is part of the Product Object (in its offers array).

Important to Know#

Updating billions of marketplace offers regularly is not feasible. The product request’s offers parameter determines how many offers Keepa retrieves/updates. Keepa always fetches the best offers, as sorted by Amazon, in all conditions. If a product has more offers than requested, those will not be retrieved.

If there are almost identical offers — same seller, same condition, and same shipping type — only the one with the cheapest price is provided in the offers list. While duplicates are not listed, their price & condition comment are provided via the offerDuplicates field.

Format#

{
    "offerId": Integer,
    "lastSeen": Integer,
    "sellerId": String,
    "isPrime": Boolean,
    "isFBA": Boolean,
    "isMAP": Boolean,
    "isShippable": Boolean,
    "isPreorder": Boolean,
    "isWarehouseDeal": Boolean,
    "isAmazon": Boolean,
    "isPrimeExcl": Boolean,
    "coupon": Integer,
    "couponHistory": Integer array,
    "condition": Integer,
    "conditionComment": String,
    "minOrderQty": Integer,
    "savingBasis": Integer,
    "savingBasisType": Integer,
    "lastStockUpdate": Integer,
    "offerCSV": Integer array,
    "stockCSV": Integer array,
    "primeExclCSV": Integer array,
    "offerDuplicates": Object array
}

Fields#

Condition values#

offerCSV format#

The offerCSV array has the format Keepa Time minutes, price, shipping cost, […]:

• The price and shipping cost are integers of the respective Amazon locale’s smallest currency unit (e.g. euro cents or yen).
• If the price or shipping cost could not be determined, they have the value -2.
• Free shipping has the shipping cost of 0.
• If an offer is not shippable or has unspecified shipping costs, the shipping cost will be -1.
• To get the newest price and shipping cost, access the last two entries of the array:

// Most recent price:
offerCSV[offerCSV.length - 2]
// Most recent shipping cost:
offerCSV[offerCSV.length - 1]

primeExclCSV format#

The primeExclCSV array has the format Keepa Time minutes, price, […]:

• The price is an integer of the respective Amazon locale’s smallest currency unit (e.g. euro cents or yen).
• If no Prime exclusive price exists, the price will be -1 or the field will be null.
• To get the most recent Prime exclusive price:

primeExclCSV[primeExclCSV.length - 1]

offerDuplicates format#

Each entry provides the price, shipping cost and condition comment of a duplicate offer (same seller, condition and shipping type) that was excluded from the main offers list because it was not the cheapest:

"offerDuplicates": [{
    "price": 1900,
    "shipping": 400,
    "conditionComment": "Open Box, Works great!"
}]

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

const unixMs = (keepaTime + 21564000) * 60000;
const unixSeconds = (keepaTime + 21564000) * 60;
const date = new Date(unixMs);

Example#

Offer objects are retrieved via the Product Request with the optional offers parameter (how many offers to retrieve, see the endpoint page for parameter details and token cost). Add the stock parameter to also receive stockCSV data.

KeepaAPI api = new KeepaAPI("YOUR_API_KEY");
Request r = Request.getProductRequest(AmazonLocale.US, null, 20, "B0F3GWXLTS");
api.sendRequest(r)
    .done(result -> {
        Product product = result.products[0];
        for (Offer offer : product.offers) {
            System.out.println(offer.sellerId + "  " + offer.condition);
        }
    })
    .fail(failure -> System.out.println(failure));

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

$api = new KeepaAPI("YOUR_API_KEY");
$response = $api->sendRequestWithRetry(Request::getProductRequest(AmazonLocale::US, 20, null, null, 1, true, ['B0F3GWXLTS']));
if ($response->status == ResponseStatus::OK) {
    $product = $response->products[0];
    print_r($product->offers);
}

import requests

params = {"key": "YOUR_API_KEY", "domain": 1, "asin": "B0F3GWXLTS", "offers": 20}
r = requests.get("https://api.keepa.com/product", params=params)
data = r.json()

for offer in data["products"][0]["offers"]:
    price = offer["offerCSV"][-2]
    shipping = offer["offerCSV"][-1]
    print(offer["sellerId"], offer["condition"], price, shipping, offer["lastSeen"])

const res = await fetch("https://api.keepa.com/product?key=YOUR_API_KEY&domain=1&asin=B0F3GWXLTS&offers=20");
const data = await res.json();

for (const offer of data.products[0].offers) {
  const price = offer.offerCSV[offer.offerCSV.length - 2];
  const shipping = offer.offerCSV[offer.offerCSV.length - 1];
  console.log(offer.sellerId, offer.condition, price, shipping, offer.lastSeen);
}

curl -s "https://api.keepa.com/product?key=YOUR_API_KEY&domain=1&asin=B0F3GWXLTS&offers=20"

Example response#

The offer objects are contained in the offers array of each product object. The first offer below is a Warehouse Deal in “Used - Very Good” condition with a detected duplicate; the second is a new-condition FBA offer with a 15% coupon and a Prime exclusive price.

{
  "timestamp": 1753747260000,
  "tokensLeft": 280,
  "refillIn": 42000,
  "refillRate": 5,
  "tokensConsumed": 6,
  "processingTimeInMs": 312,
  "products": [
    {
      "asin": "B0F3GWXLTS",
      "domainId": 1,
      "title": "Example Bluetooth Speaker (Black)",
      "liveOffersOrder": [1, 0],
      "offers": [
        {
          "offerId": 4,
          "lastSeen": 7665120,
          "sellerId": "A2L77EE7U53NWQ",
          "isPrime": true,
          "isFBA": true,
          "isMAP": false,
          "isShippable": true,
          "isPreorder": false,
          "isWarehouseDeal": true,
          "isAmazon": false,
          "isPrimeExcl": false,
          "condition": 3,
          "conditionComment": "The item may come repackaged. Small cosmetic imperfection on top.",
          "lastStockUpdate": 7665120,
          "offerCSV": [7621040, 2299, 0, 7648900, 2149, 0, 7665120, 2079, 0],
          "offerDuplicates": [
            {
              "price": 2199,
              "shipping": 0,
              "conditionComment": "Open Box, works great!"
            }
          ]
        },
        {
          "offerId": 11,
          "lastSeen": 7665080,
          "sellerId": "A1B2C3D4E5F6G7",
          "isPrime": true,
          "isFBA": true,
          "isMAP": false,
          "isShippable": true,
          "isPreorder": false,
          "isWarehouseDeal": false,
          "isAmazon": false,
          "isPrimeExcl": true,
          "coupon": -15,
          "couponHistory": [7648900, 500, 7665080, -15],
          "condition": 1,
          "minOrderQty": 2,
          "lastStockUpdate": 7665080,
          "offerCSV": [7590200, 2999, 449, 7648900, 2899, 0, 7665080, 2849, 0],
          "primeExclCSV": [7648900, 2699, 7665080, 2649]
        }
      ]
    }
  ]
}

Response shortened for readability; illustrative values. Prices are integers in the locale’s smallest currency unit (here: US cents, e.g. 2079 = $20.79); timestamps are Keepa Time minutes (e.g. 7665120 → Unix ms (7665120 + 21564000) * 60000 = 1753747200000).