> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon API

> Search Amazon and read its product pages as JSON: ranked products with prices, ratings and review counts, and each product's price, stock, seller, images, specs and options.

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**.

## Search

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "COMMERCE_SERP", "payload": { "site": "amazon", "query": "wireless earbuds", "limit": 3 } }'
```

Submit the task, then poll `GET /v1/async/task/{id}` or receive its webhook. See [Async tasks](https://docs.querying.ai/concepts/async-tasks.md).

### 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

```json theme={"theme":"css-variables"}
{
  "site": "amazon",
  "query": "wireless earbuds",
  "country": "US",
  "returnedCount": 3,
  "products": [
    {
      "rank": 1,
      "productId": "B0HJTS6LXB",
      "title": "Wireless Earbuds, 2026 Bluetooth 5.4 Headphones Bass Stereo Ear Buds with Noise Cancelling Mic, LED Display in Ear Earphones 50H Playtime Ear Buds, IP7 Waterproof for Laptop Pad Phones Dark Black",
      "url": "https://www.amazon.com/dp/B0HJTS6LXB",
      "price": 19.99,
      "currency": "USD",
      "rating": 4.6,
      "reviewCount": 656,
      "imageUrl": "https://m.media-amazon.com/images/I/61aSuH86kYL._AC_UY218_.jpg"
    },
    {
      "rank": 2,
      "productId": "B0FQFB8FMG",
      "title": "Apple AirPods Pro 3 Wireless Earbuds with Active Noise Cancellation",
      "url": "https://www.amazon.com/dp/B0FQFB8FMG",
      "price": 179,
      "currency": "USD",
      "rating": 4.4,
      "reviewCount": 18076,
      "imageUrl": "https://m.media-amazon.com/images/I/61solmQSSlL._AC_UY218_.jpg"
    },
    {
      "rank": 3,
      "productId": "B0BQPNMXQV",
      "title": "JBL Vibe Beam - True Wireless Earbuds - Black",
      "url": "https://www.amazon.com/dp/B0BQPNMXQV",
      "price": 29.95,
      "currency": "USD",
      "rating": 4.2,
      "reviewCount": 41710,
      "imageUrl": "https://m.media-amazon.com/images/I/41+1Csr1pSL._AC_UY218_.jpg"
    }
  ]
}
```

### 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

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "COMMERCE_PRODUCT", "payload": { "url": "https://www.amazon.com/dp/B0HJTS6LXB" } }'
```

### 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

```json theme={"theme":"css-variables"}
{
  "site": "amazon",
  "country": "US",
  "url": "https://www.amazon.com/dp/B0HJTS6LXB",
  "productId": "B0HJTS6LXB",
  "title": "Wireless Earbuds, 2026 Bluetooth 5.4 Headphones Bass Stereo Ear Buds with Noise Cancelling Mic, LED Display in Ear Earphones 50H Playtime Ear Buds, IP7 Waterproof for Laptop Pad Phones Dark Black",
  "brand": "XIAOWTEK",
  "price": 19.99,
  "listPrice": 199.99,
  "currency": "USD",
  "inStock": true,
  "seller": "duanyuekj",
  "rating": 4.6,
  "reviewCount": 656,
  "images": [
    "https://m.media-amazon.com/images/I/61aSuH86kYL._AC_SL1500_.jpg",
    "https://m.media-amazon.com/images/I/614SJ1xXHDL._AC_SL1500_.jpg"
  ],
  "description": "LED Power Display and 50H Playback: Dual digital LED power display outside of the case is to show the power level for charging case and earbuds. When charging for the case, the LED light will start…",
  "descriptionImages": [
    "https://m.media-amazon.com/images/S/aplus-media-library-service-media/bd0bc2d5-cf30-4f89-bb94-79fa935a35c4.__CR0,0,1464,600_PT0_SX1464_V1___.jpg",
    "https://m.media-amazon.com/images/S/aplus-media-library-service-media/a0abce46-fbc8-4054-9705-77153bb852a8.__CR0,0,1464,600_PT0_SX1464_V1___.jpg"
  ],
  "specs": [
    { "name": "Brand", "value": "XIAOWTEK" },
    { "name": "Color", "value": "Dark Black" },
    { "name": "Ear Placement", "value": "In Ear" }
  ],
  "options": [{ "name": "Color", "values": ["Blue", "Carbon Black", "Dark Black", "Pink"] }],
  "categories": [
    "Electronics",
    "Headphones, Earbuds & Accessories",
    "Headphones & Earbuds",
    "Earbud Headphones"
  ]
}
```

### 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.

## Related

* [Walmart](https://docs.querying.ai/engines/walmart.md)
* [Target](https://docs.querying.ai/engines/target.md)
* [eBay](https://docs.querying.ai/engines/ebay.md)
* [All Commerce stores](https://docs.querying.ai/engines/overview.md#commerce)
* [Credits and limits](https://docs.querying.ai/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.