Skip to main content
Search Amazon (amazon.com) and read its product pages through the async task API. Send COMMERCE_SERP with site amazon to get the products a search shows, in the store’s order, or COMMERCE_PRODUCT with a product’s url to read that product. A completed search or product page costs 1 credit.
Submit the task, then poll GET /v1/async/task/{id} or receive its webhook. See Async tasks.

Parameters

  • site: Required. amazon.
  • query: Required. The search query, 1-500 characters.
  • limit: Optional integer from 1 to 40, default 20.
  • country: Optional. Defaults to US, the store’s country. Any other country is rejected with 422 REGION_UNSUPPORTED.
Only the payload fields listed above are accepted. Omit include: even include: {} returns 422 VALIDATION_ERROR on payload.include before credits are held.

Response example

Result fields

  • site, query and country echo the request. returnedCount is the number of entries in products.
  • Each product includes rank, productId, title and url. productId is the ASIN. rank follows the store’s default order, and listings the store marks as sponsored are left out.
  • price, rating, reviewCount and imageUrl appear when the results page shows them. price is a number in the product’s currency (ISO 4217); when sizes are priced apart, it is the lowest one. One Amazon search can list more than one currency.
  • rating uses a five-point scale. Abbreviated review counts such as 999+ are left out.
  • Each search returns products from the store’s first results page.

Product page

Parameters

  • url: Required. A product page on Amazon, up to 2,048 characters: amazon.com/dp/{ASIN} or amazon.co.jp/dp/{ASIN}. Product url values from a search work as they are. Parameters the result does not depend on, such as tracking codes, are dropped before the page is read. Other addresses of the same page also work, such as /gp/product/{ASIN}.
  • country: Optional. Defaults to the page’s country: US on amazon.com and JP on amazon.co.jp. Any other country is rejected with 422 REGION_UNSUPPORTED.
Only the payload fields listed above are accepted. Omit include: even include: {} returns 422 VALIDATION_ERROR on payload.include before credits are held.

Response example

Result fields

  • site, country, url and productId identify the page. url is the page that was read, and productId matches the one a search returns.
  • title is always present. brand, price, listPrice, currency, inStock, seller, rating, reviewCount, images, description, descriptionImages, specs, options, categories and gtin appear when the page shows them.
  • price is what a shopper pays as the page first shows it, before coupons and delivery, in currency (ISO 4217). listPrice is the regular price the page strikes through, present when it is above price. inStock is the product’s stock status. seller is the merchant selling it. amazon.co.jp pages return country JP and prices in JPY. When Amazon picks no featured offer for a product, the page shows no price, so price, currency, seller and inStock come from the first seller with a price in the product’s offer list.
  • rating uses a five-point scale with two decimals. reviewCount is the number of reviews.
  • images lists up to 30 photos from the product’s gallery, in page order.
  • description is plain text with one line per paragraph, up to 10,000 characters; text that appears only inside images is not included.
  • descriptionImages lists up to 300 images from the product description, in page order. Banners and notices that sellers place in their description come along, and text inside the images is not read.
  • specs lists up to 100 { name, value } pairs from the product details. options lists up to 20 choices such as size or color, each with up to 100 values; the other fields describe the choice the page opens on. categories runs from the broadest category to the narrowest, up to 10 levels. gtin is the UPC, EAN or JAN the page lists.

Errors and billing

  • A search that returns no products ends as a failed task.
  • A product page the store answers with 404 or 410, such as a removed product, ends the task with PAGE_UNAVAILABLE, and the message carries the store’s answer. When the store refuses the read with 403, 412, 429 or 435, the task waits and asks again for up to 6 minutes. Other failed reads, and a refusal that lasts longer, end with ENGINE_NO_RESULT.
  • Only completed tasks are charged: 1 credit for a search or a product page.