Endpoints
Every endpoint takes country, a marketplace code such as US, DE or JP (default US). Each endpoint has its own page with an example request and a recorded response.
GET /search · Search products
Keyword search on one Amazon marketplace. Returns each result's position, ASIN, title, price, list price, rating, ratings count, sponsored, Amazon's Choice and Best Seller flags, and "bought in past month" text. Sponsored and organic placements of the same ASIN are both returned, with their page positions. `is_prime` is true when Amazon shows a Prime badge; null when unknown (logged-out pages rarely show Prime).
| Name | Required | Values | Notes |
|---|
query | yes | string | Search keywords. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). |
|---|
page | no | 1 to 20 (default 1) | |
|---|
sort | no | relevance, price_asc, price_desc, reviews, newest, bestsellers | |
|---|
min_price | no | number | In the marketplace's currency. |
|---|
max_price | no | number | |
|---|
category | no | string | Amazon search category alias (e.g. electronics) or numeric browse node ID (e.g. 172541). |
|---|
Example request and response for /searchGET /product-details · Product details by ASIN
Everything public on the product page: title, brand, price, list price, images, rating, ratings count, availability, badges, bullet points, description, product details table, category breadcrumbs, Best Sellers Rank, "bought in past month" and whether the product has variations. `is_prime` is true when Amazon shows a Prime badge; null when unknown (logged-out pages rarely show Prime). `original_price_type` is the page's label for the original price, e.g. "Print List Price" on Kindle pages.
| Name | Required | Values | Notes |
|---|
asin | yes | matches ^[A-Za-z0-9]{10}$ | 10-character Amazon product ID (ASIN). Case and surrounding spaces are ignored. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). |
|---|
Example request and response for /product-detailsGET /product-reviews · Ratings and review highlights
Public review data from the product page: average rating, total ratings, star breakdown (% per star), Amazon's AI "Customers say" summary with topic tags and mention counts, and the top reviews Amazon shows logged-out visitors (typically 5 to 13; may be empty on some amazon.com pages, where Amazon asks visitors to sign in). Full review lists need an Amazon login and are not included. A product nobody has rated yet returns rating null and total_ratings 0. Each review has `date` (ISO YYYY-MM-DD or null) and `date_text` (Amazon's raw line), `helpful_votes` (integer or null) and `helpful_votes_text` (Amazon's raw phrase). Aspect names use display casing, e.g. "Value for money".
| Name | Required | Values | Notes |
|---|
asin | yes | matches ^[A-Za-z0-9]{10}$ | 10-character Amazon product ID (ASIN). Case and surrounding spaces are ignored. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). The playground starts on GB because amazon.com often hides reviews from signed-out visitors; leave country out and the API uses US. |
|---|
Example request and response for /product-reviewsGET /best-sellers · Best sellers and rankings
Amazon's ranked lists for a category: Best Sellers, New Releases, Movers & Shakers, Most Wished For and Gift Ideas. 50 ranks per page, 2 pages per list. Full details for the items Amazon renders (about the first 30); the rest return rank, ASIN and URL. A list Amazon reports as empty ("no ... available in this category") returns items: []. type=movers-and-shakers is currently unavailable: Amazon shows it only to signed-in visitors, and returns 400 invalid_input.
| Name | Required | Values | Notes |
|---|
category | yes | string | Category slug as in Amazon's best-seller URLs, optionally with a node ID: electronics or electronics/172541. |
|---|
type | no | bestsellers, new-releases, movers-and-shakers, most-wished-for, gift-ideas (default bestsellers) | bestsellers (default), new-releases, most-wished-for, gift-ideas. movers-and-shakers is currently unavailable: Amazon shows it only to signed-in visitors (returns 400 invalid_input). |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). |
|---|
page | no | 1, 2 (default 1) | 1 = ranks 1 to 50, 2 = ranks 51 to 100. |
|---|
Example request and response for /best-sellersGET /seller-products · Products sold by a seller
Lists the products one third-party seller offers on one Amazon marketplace, from the seller's storefront. Returns the same result fields as /search (position, ASIN, title, price, list price, rating, ratings count, flags). Find a seller ID in the URL of the seller's page (seller=...) or in a product page's offers. Not available on ZA.
| Name | Required | Values | Notes |
|---|
seller_id | yes | matches ^[A-Za-z0-9]{10,16}$ | Amazon seller ID, 10 to 16 letters and digits. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). Not available on ZA (returns 400 country_unavailable). |
|---|
page | no | 1 to 20 (default 1) | |
|---|
sort | no | relevance, price_asc, price_desc, reviews, newest, bestsellers | |
|---|
Example request and response for /seller-productsGET /product-lookup · Look up a product by barcode
Searches one Amazon marketplace for a UPC, EAN, ISBN or GTIN and returns the organic search results, best match first, with sponsored results removed. Same result fields as /search. Matches are not verified against the barcode: search cards carry no barcode, so check the top result before relying on it (call /product-details with its ASIN). If Amazon searched for something other than the code (it corrected the query), results is [].
| Name | Required | Values | Notes |
|---|
identifier | yes | string | UPC, EAN, ISBN or GTIN: 8, 10, 12, 13 or 14 digits (ISBN-10 may end in X). Hyphens and spaces are ignored. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). |
|---|
Example request and response for /product-lookupGET /product-offers · All seller offers for a product
Every offer Amazon shows for one ASIN on one marketplace: the featured (pinned) offer first, then the other sellers, each with condition, price, list price, seller name, ID and rating, ships-from, sold/fulfilled by Amazon, and delivery text. Null where Amazon shows no value. offers is [] when Amazon lists none. total_offers is Amazon's count of offers besides the pinned one (null on page 2 and later, which list only the next sellers, about 10 per page; the pinned offer is returned on page 1 only). Every response is checked to come from the requested marketplace; a page from another country is never returned.
| Name | Required | Values | Notes |
|---|
asin | yes | matches ^[A-Za-z0-9]{10}$ | 10-character Amazon product ID (ASIN). Case and surrounding spaces are ignored. |
|---|
page | no | 1 to 20 (default 1) | Page of other offers, 1 to 20. Default 1. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). |
|---|
Example request and response for /product-offersGET /deals · Today's deals
The first page of Amazon's Today's Deals for one marketplace (about 30 deals), each with deal ID, ASIN, title, image, deal price, list price, savings percent, Amazon's deal badge text, percent claimed and end time. Null where Amazon shows no value; ends_at is usually null because the deals page does not publish end times. Only page 1 is available: Amazon serves the same deals for later pages. Every response is checked to come from the requested marketplace; a page from another country is never returned.
| Name | Required | Values | Notes |
|---|
page | no | 1 to 1 (default 1) | Only 1 is accepted: Amazon serves the same deals for later pages. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). |
|---|
Example request and response for /dealsGET /seller-profile · Seller profile
Public profile of one third-party seller on one marketplace: name, business name and address, storefront link, logo, rating out of 5, percent positive and number of ratings in the last 12 months, lifetime ratings and the star breakdown in percent. Null where Amazon shows no value. Every response is checked to come from the requested marketplace; a page from another country is never returned. Marketplaces where the seller page cannot be read return 400 country_unavailable.
| Name | Required | Values | Notes |
|---|
seller_id | yes | matches ^[A-Za-z0-9]{10,16}$ | Amazon seller ID, 10 to 16 letters and digits. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). Not available on IE, SG, ZA (returns 400 country_unavailable). |
|---|
Example request and response for /seller-profileGET /categories · Best-seller categories
The category tree of Amazon's Best Sellers for one marketplace: the top-level departments, or the subcategories of one category. Each entry has the category name, its node ID (null for a department), a `path` and the best-sellers URL. `path` is exactly what `/best-sellers` and `/categories` accept as `category`. A category with no subcategories returns an empty list. Names come in the marketplace language. `parent` echoes the requested category, or null for the top level. Every response is checked to come from the requested marketplace; a page from another country is never returned.
| Name | Required | Values | Notes |
|---|
category | no | string | A `path` from a previous response: a department slug (electronics) or slug and node ID (electronics/172541). Omit for the top-level departments. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). |
|---|
Example request and response for /categoriesGET /search-autocomplete · Search autocomplete
The suggestions Amazon's search box offers for a prefix on one marketplace, in Amazon's order, as plain strings. `query` echoes the prefix. An empty `suggestions` list is a valid answer. Suggestions come in the marketplace language.
| Name | Required | Values | Notes |
|---|
query | yes | string | The text typed so far, 1 to 100 characters. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). Not available on IN (returns 400 country_unavailable). |
|---|
Example request and response for /search-autocompleteGET /products-by-category · Products in a category
Lists the products Amazon shows for a category with no search keyword, one page at a time. Takes the same category values as /search: a search alias such as electronics, or a numeric browse node ID. Returns the same result fields as /search.
| Name | Required | Values | Notes |
|---|
category | yes | matches ^[A-Za-z0-9-]+$ | Amazon search category alias (e.g. electronics) or numeric browse node ID (e.g. 172282). Same values as /search. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). |
|---|
page | no | 1 to 20 (default 1) | |
|---|
sort | no | relevance, price_asc, price_desc, reviews, newest, bestsellers | |
|---|
Example request and response for /products-by-categoryGET /seller-reviews · A seller's buyer feedback
Buyer feedback for one third-party seller, newest first: star rating, comment, rater name, date (YYYY-MM-DD plus Amazon's original text), and whether Amazon struck the feedback through with its reason. The first call returns the newest feedback (usually 5 entries); pass `next_cursor` back as `cursor` for the next page. `next_cursor` is null on the last page. Every response is checked to come from the requested marketplace. Marketplaces where the seller page cannot be read return 400 country_unavailable.
| Name | Required | Values | Notes |
|---|
seller_id | yes | matches ^[A-Za-z0-9]{10,16}$ | Amazon seller ID, 10 to 16 letters and digits. |
|---|
cursor | no | string | The `next_cursor` value from the previous response. Omit it for the first page. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). Not available on BE, IE, SG, ZA (returns 400 country_unavailable). |
|---|
Example request and response for /seller-reviewsGET /promo-code-details · Promotion details
An Amazon promotion by its ID (the code in an amazon.com/promotion/psp/<promo_id> link, shown on product pages next to coupons and 'Buy more & save' offers): title, banner, schedule, how-to-claim steps, the note under them and the seller running it. The promotion's product list is not returned: Amazon loads it only in the browser. Every response is checked to come from the requested marketplace. An unknown or ended promotion returns 404 not_found.
| Name | Required | Values | Notes |
|---|
promo_id | yes | matches ^[A-Za-z0-9]{8,20}$ | The promotion ID from an amazon.com/promotion/psp/<promo_id> link. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). |
|---|
Example request and response for /promo-code-detailsGET /influencer-profile · Influencer storefront profile
An Amazon influencer's storefront profile by handle: display name, bio, profile image, top-creator badge, social links and the trending products on the storefront (ASIN, image, price, deal flag). Every response is checked to come from the requested marketplace. An unknown handle returns 404 not_found.
| Name | Required | Values | Notes |
|---|
handle | yes | matches ^[A-Za-z0-9][A-Za-z0-9._-]{1,63}$ | The storefront name from amazon.com/shop/<handle>. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). Not available on MX, BR, GB, SA, EG, JP, IE, ZA (returns 400 country_unavailable). |
|---|
Example request and response for /influencer-profileGET /influencer-posts · Influencer video posts
The newest video posts (up to 10) on an Amazon influencer's storefront: title, duration, thumbnail, stream URL, post link and the ASINs of the products each video features. Photo and idea-list posts are not included: Amazon loads them only in the browser. An unknown handle returns 404 not_found.
| Name | Required | Values | Notes |
|---|
handle | yes | matches ^[A-Za-z0-9][A-Za-z0-9._-]{1,63}$ | The storefront name from amazon.com/shop/<handle>. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). Not available on MX, BR, GB, SA, EG, JP, IE, ZA (returns 400 country_unavailable). |
|---|
Example request and response for /influencer-postsGET /scrape-url · Any Amazon page as HTML
The HTML of any page on one of the 23 Amazon marketplaces, for data the other endpoints don't parse. The marketplace comes from the URL's domain; pass `country` only to double-check it. Not parsed: you get `{ url, html }`. Pages Amazon shows only to signed-in visitors return 403 sign_in_required, and a page that came back from another marketplace returns 502 wrong_marketplace.
| Name | Required | Values | Notes |
|---|
url | yes | string | A full URL on www.amazon.com, www.amazon.co.uk, www.amazon.de or another of the 23 marketplaces. |
|---|
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Optional check: when given, it must be the marketplace of the url's domain, else 400 invalid_input. |
|---|
Example request and response for /scrape-url