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

# Commerce Search API (COMMERCE_SERP)

> Search Amazon, Walmart, eBay, AliExpress, Google Shopping, Sephora, Coupang, Olive Young, Rakuten, Flipkart, Zalando and more, one storefront per task, and get ranked products with prices, ratings and review counts in one shape.

Search one storefront's products and receive the ranked list as JSON through the async task API. Pick the storefront with `site`; every site returns the same product fields. A completed search costs **3 credits**.

## Request

```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": 20 } }'
```

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

## Parameters

* `site`: Required. The storefront to search, from the table below.
* `query`: Required search query, 1-500 characters.
* `country`: Optional. Defaults to the site's country. Any other country is rejected with `422 REGION_UNSUPPORTED`.
* `limit`: Optional integer from 1 to 40. Default 20.

| `site` | Storefront | `country` |
| - | - | - |
| `amazon` | amazon.com | `US` |
| `walmart` | walmart.com | `US` |
| `target` | target.com | `US` |
| `ebay` | ebay.com | `US` |
| `aliexpress` | aliexpress.com | `US` |
| `google_shopping` | shopping.google.com | `US` |
| `sephora` | sephora.com | `US` |
| `ulta` | ulta.com | `US` |
| `coupang` | coupang.com | `KR` |
| `oliveyoung` | oliveyoung.co.kr | `KR` |
| `11st` | 11st.co.kr | `KR` |
| `lotteon` | lotteon.com | `KR` |
| `musinsa` | musinsa.com | `KR` |
| `kurly` | kurly.com | `KR` |
| `rakuten` | rakuten.co.jp | `JP` |
| `yahoo_shopping` | shopping.yahoo.co.jp | `JP` |
| `qoo10` | qoo10.jp | `JP` |
| `flipkart` | flipkart.com | `IN` |
| `myntra` | myntra.com | `IN` |
| `nykaa` | nykaa.com | `IN` |
| `zalando` | zalando.de | `DE` |

## Response example

```json theme={"theme":"css-variables"}
{
  "site": "amazon",
  "query": "wireless earbuds",
  "country": "US",
  "returnedCount": 1,
  "products": [
    {
      "rank": 1,
      "productId": "B0CHWRXH8B",
      "title": "Wireless Earbuds, Bluetooth 5.3 Headphones",
      "url": "https://www.amazon.com/dp/B0CHWRXH8B",
      "price": 24.99,
      "currency": "USD",
      "rating": 4.6,
      "reviewCount": 19406
    }
  ]
}
```

## 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 storefront's own product ID, such as the ASIN on Amazon, the item number on eBay or `shop:item` on Rakuten. `rank` follows the storefront's default order. Listings the storefront marks as sponsored are left out on every site except Coupang.
* `price`, `rating`, `reviewCount`, `imageUrl` and `brand` appear when the results page shows them. `price` is a number in the product's own `currency` (ISO 4217): one Amazon search can list more than one currency. When sizes are priced apart, `price` is the lowest one. Target prices are those of its default online store. AliExpress prices are the sale prices shown to a signed-out shopper in the US.
* `rating` uses a five-point scale. Kurly and Zalando show no ratings, AliExpress shows stars without a rating count, and abbreviated counts such as 999+ are left out. `brand` comes from Target, Sephora, Ulta, Olive Young, Lotte ON, Musinsa, Yahoo! Shopping, Qoo10, Flipkart, Myntra, Nykaa and Zalando, which list it apart from the title.
* On `google_shopping`, `productId` is Google's product ID, or the offer ID for a listing Google has not grouped into a product. Google's page links no product or merchant page, so `url` is the Google Shopping results page the product was ranked on, with `#product={productId}&title={title}` at the end. Pass that `url` to [Commerce Product](/engines/commerce-product.md) to read the product's stores, specs and description. `seller` names the store Google lists first, and `reviewCount` appears only when Google shows the exact count (below 1,000).
* Each search returns products from the storefront's first results page. That page lists up to 30 products on Yahoo! Shopping, 32 on Myntra and 24 on Zalando. Flipkart's page has 40 places and Nykaa's 20, sponsored listings included.
* When a storefront sends a search to another page, the products come from that page: Ulta sends some brand names to the brand page, Target sends some searches to a related search, and Nykaa shows the category page for searches that name a category.
* A search that returns no products ends as a failed task. Billing applies per completed search.

## Related

* [Commerce Product](/engines/commerce-product.md)
* [Engine overview](/engines/overview.md)
* [Credits and limits](/concepts/credits-and-limits.md)


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