Skip to main content
Nine endpoints, one key. Every call reads one live Amazon page and costs 1 request. Every path is under /v1/amazon. Search keeps sponsored cards and flags them; lookup and seller products drop them. Fields Amazon does not show come back null or empty. See the Amazon API: overview, pricing, and free tier.

Marketplace and location

Every endpoint takes two optional parameters. The response echoes both in query. The request is made from the marketplace’s country, and pages are read in English. Without zip_code, Amazon picks a delivery location in that country itself; the one it used is in product.delivery_location.
GET /v1/amazon/search
Response time: 2–5 s typical, 60 s limit. Page fetch. How to read this. Send q, category_id, or both. Send next_cursor back as cursor for the next page; there is no limit. The filters are Amazon’s own search refinements, so results match what a shopper sees with the same filters ticked. Amazon numbers most refinements per marketplace, and not every marketplace offers every one: prime outside the US, condition=renewed on ca, in, de, be, and jp, and condition=used on in and es return 400 before any request is charged. Each hit is position, asin, title, url, price_text, price, currency, original_price_text, original_price, rating, ratings_count, badge (for example Overall Pick), sales_volume (for example 1K+ bought in past month), image_url, sponsored, is_prime, delivery, coupon, and other_offers.
  • sponsored is true for paid placements. They keep their place in position, as on the page.
  • is_prime is true when the card offers Prime delivery and false when it shows delivery without Prime. Amazon shows Prime only to US visitors who are not logged in, so it is null on every other marketplace.
  • delivery is the card’s delivery line, e.g. FREE delivery Tomorrow, Sep 26. For Prime items this is the Prime member date.
  • coupon is { text, price_text, price }, e.g. 5% off coupon and the price after it, or null.
  • other_offers is the card’s “More Buying Choices” line: { min_price_text, min_price, offers_count }, the cheapest other new or used offer and how many there are. offers_count is a lower bound when Amazon prints 8+.

Product details

GET /v1/amazon/product?asin=B0CF3VGQFL Response time: 3–6 s typical, 60 s limit. Page fetch. How to read this. The body is product:

Product reviews

GET /v1/amazon/reviews?asin=B0CF3VGQFL&country=ca Response time: 4–7 s typical, 60 s limit. Page fetch. How to read this.
Not available on amazon.com. amazon.com shows reviews only to signed-in shoppers, and Clair does not sign in, so country=us, the default, returns 400 unsupported_parameter and is not charged. Pass any other marketplace: gb, ca, au, in, de, es, nl, be, or jp. Many US products sell on amazon.ca and amazon.co.uk under the same ASIN. For a US product’s rating and rating_distribution, use product details, which works on every marketplace.
The reviews the product page shows without sign-in, up to about 13 (fewer when the product has fewer), plus product.rating_distribution. Amazon keeps the full review list behind sign-in on every marketplace, so there is no page or cursor, and next_cursor is always null. Amazon sometimes serves the page without its review block; Clair then reads the page once more, still for 1 request. If Amazon asks for a sign-in instead of showing reviews, the call fails with 502 scrape_failed and is refunded. The response has product (asin, title, rating, ratings_count, rating_distribution), then the list fields. Each review in results is review_id, title, body, rating, author, date (ISO), country, verified_purchase, variant, helpful_votes_count, and url.

Product offers

GET /v1/amazon/offers?asin=1098145356 Response time: 2–4 s typical, 60 s limit. Page fetch. How to read this. Every seller in Amazon’s all-offers panel, after product (asin, title, rating, ratings_count, url). Each offer in results is position, condition (New, Used - Like New, …), price, original_price, delivery, ships_from, and seller with seller_id, name, rating, ratings_count, and positive_percent. results is empty when Amazon lists none. The panel is one page, so next_cursor is always null.

GTIN lookup

GET /v1/amazon/lookup?gtin=9781098145354 Response time: 2–4 s typical, 60 s limit. Page fetch. How to read this. Returns product cards in the search shape. Use results[0].asin.

Seller profile

GET /v1/amazon/seller?seller_id=AWZI6BA70DZZD Response time: 1–3 s typical, 60 s limit. Page fetch. How to read this. The body is seller: seller_id, name, logo_url, rating, ratings_count, positive_percent, ratings for last_30_days, last_90_days, last_12_months, and lifetime, rating_distribution, business_name, business_address, about, storefront_url, and recent feedback (rating, text, author, date).

Seller products

GET /v1/amazon/seller-products?seller_id=AWZI6BA70DZZD&page=1 Response time: 2–4 s typical, 60 s limit. Page fetch. How to read this. The seller’s storefront as product cards in the search shape, up to 10 pages; next_cursor opens the next one.

Best sellers

GET /v1/amazon/bestsellers?category=electronics Response time: 1–3 s typical, 60 s limit. Page fetch. How to read this. Each result is rank, asin, title, url, price, rating, ratings_count, and image_url. category names the ranking, and subcategories[] has name, category, and node_id for drilling down. Amazon ranks 60 a category over 2 pages; next_cursor opens page 2.

Categories

GET /v1/amazon/categories Response time: 1–3 s typical, 60 s limit. Page fetch. How to read this. Without parameters, the top-level departments. With category (and optionally node_id), that node’s children, after parent. Each entry in results is name, category, and node_id. Use node_id as category_id in search or as node_id in best sellers.

Not available

Amazon renders deals client-side and puts full review pagination behind sign-in, so neither is offered. Reviews on amazon.com need a sign-in too, so the reviews endpoint does not take country=us. Auth, plans, rate limits, and error codes: Authentication.