Amazon API
The TrueScrape Amazon API exposes 4 public endpoints covering All seller offers for a product, Product details and Search results. Every call is a GET against public, logged-out pages and returns the same unified schema as every other platform here. Calls cost 1–3 credits each. A cache hit is free, and a failed or empty response is never charged.
Endpoints
| Endpoint | Returns | Credits | Cacheable | Batchable |
|---|---|---|---|---|
| /v1/amazon/offers | All seller offers for a product | 3 | yes | yes |
| /v1/amazon/product | Product details | 3 | yes | yes |
| /v1/amazon/search | Search results | 3 | yes | yes |
| /v1/amazon/shop | Amazon Shop page | 1 | yes | yes |
Reference
GET
/v1/amazon/offers3 creditscacheablebatchableAll seller offers for a product
Every offer on an Amazon listing (price, seller, condition, Prime eligibility and shipping), alongside the product itself.
| Parameter | Type | Required | Description |
|---|---|---|---|
| asin | string | yes | Amazon ASIN, e.g. "B08N5WRWNW" |
| tld | string | no | Marketplace TLD, default "com". One of: com, co.uk, ca, de, es, fr, ie, it, co.jp, co.za, in, cn, com.sg, com.mx, ae, com.br, nl, com.au, com.tr, sa, se, pl |
| country_code | string | no | Best-effort locale hint (ISO 3166-1 alpha-2). |
| condition | new | used_like_new | used_very_good | used_good | used_acceptable | no | Filter offers to one condition. |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
curl
curl "$API/v1/amazon/offers?asin=%3Casin%3E&cache_max_age=7d" \
-H "x-api-key: $KEY"TypeScript
const query = new URLSearchParams({
asin: '<asin>',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/amazon/offers?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 3 credits, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/amazon/offers",
params={
"asin": "<asin>",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or upstream_rate_limited. Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_blocked / upstream_schema_drift. Not charged |
| 504 | upstream_timeout. Not charged |
GET
/v1/amazon/product3 creditscacheablebatchableProduct details
Public details for one Amazon listing: title, brand, price, availability, rating, specifications and an inline review sample.
| Parameter | Type | Required | Description |
|---|---|---|---|
| asin | string | yes | Amazon ASIN, e.g. "B08N5WRWNW" |
| tld | string | no | Marketplace TLD, default "com". One of: com, co.uk, ca, de, es, fr, ie, it, co.jp, co.za, in, cn, com.sg, com.mx, ae, com.br, nl, com.au, com.tr, sa, se, pl |
| country_code | string | no | Best-effort locale hint (ISO 3166-1 alpha-2). |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
Returns one Product.
Fields
| Field | Type | Present | Description |
|---|---|---|---|
| platform | one of 32 strings | always | |
| id | string | always | The product id on its marketplace: the ASIN on Amazon, the item id on Walmart and eBay. Always a string. |
| title | string | null | always | |
| brand | string | null | always | |
| description | string | null | always | |
| url | string | null | always | |
| imageUrls | string[] | always | |
| price | number | null | always | The price a buyer pays now, in `currency`. |
| currency | string | null | always | ISO 4217 currency code for the amounts in this record, such as USD or EUR. |
| listPrice | number | null | always | The struck-through reference price shown next to `price` when the listing shows a discount. |
| availability | in_stock | out_of_stock | preorder | discontinued | unknown | null | always | Stock status. `unknown` means the listing showed a status that could not be read as one of the other values. |
| rating | number | null | always | Average customer rating, out of 5. |
| reviewCount | number | null | always | Number of ratings or reviews the marketplace reports for the product, not the number of entries in `reviews`. |
| sellerName | string | null | always | |
| shipsFrom | string | null | always | The party the item ships from, as the listing names it. |
| marketplace | string | null | always | The marketplace site this product was read from, such as `amazon.co.uk`. |
| categories | string[] | always | Category breadcrumb, from the broadest category to the most specific. |
| featureBullets | string[] | always | |
| attributes | Record<string, string> | always | Specifications as label and value pairs. Which labels appear varies by marketplace and category. |
| reviews | ProductReview[] | always | A sample of reviews shown on the product page, not the full review list. |
| fetchedAt | string | always | When this record was retrieved, as an ISO 8601 timestamp. |
curl
curl "$API/v1/amazon/product?asin=%3Casin%3E&cache_max_age=7d" \
-H "x-api-key: $KEY"TypeScript
const query = new URLSearchParams({
asin: '<asin>',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/amazon/product?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 3 credits, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/amazon/product",
params={
"asin": "<asin>",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or upstream_rate_limited. Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_blocked / upstream_schema_drift. Not charged |
| 504 | upstream_timeout. Not charged |
GET
/v1/amazon/search3 creditscacheablebatchableSearch results
Public Amazon search results for a query: position, price, rating and badges per item.
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | yes | Search terms, e.g. "wireless mouse" |
| tld | string | no | Marketplace TLD, default "com". One of: com, co.uk, ca, de, es, fr, ie, it, co.jp, co.za, in, cn, com.sg, com.mx, ae, com.br, nl, com.au, com.tr, sa, se, pl |
| country_code | string | no | Best-effort locale hint (ISO 3166-1 alpha-2). |
| page | number | no | defaults to 1 |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
Returns a list of SearchResultItem in data.items.
Fields
| Field | Type | Present | Description |
|---|---|---|---|
| platform | one of 32 strings | always | |
| position | number | null | always | Rank of the result on the page it was read from, starting at 1, in the order the source served it. |
| id | string | null | always | The listing id on its platform, such as an Amazon ASIN. Where the source shows no id, this is the result URL, or the title when there is no URL. |
| title | string | null | always | |
| url | string | null | always | |
| thumbnailUrl | string | null | always | |
| price | number | null | always | Price shown on the result, in `currency`. Where a price range is shown, the lowest price. |
| currency | string | null | always | ISO 4217 currency code for the amounts in this record, such as USD or EUR. |
| listPrice | number | null | always | The struck-through reference price shown on the result, when there is one. |
| rating | number | null | always | Average customer rating, out of 5. |
| reviewCount | number | null | always | |
| sellerName | string | null | always | |
| availability | in_stock | out_of_stock | preorder | discontinued | unknown | null | always | Stock status. `unknown` means the listing showed a status that could not be read as one of the other values. |
| badges | string[] | always | Labels shown on the result, such as Best Seller or Amazon's Choice. |
| isSponsored | boolean | null | always | True for a paid placement. False only where the source marks a result as not sponsored; a result with no sponsored label is null. |
| fetchedAt | string | always | When this record was retrieved, as an ISO 8601 timestamp. |
curl
curl "$API/v1/amazon/search?query=ai%20agents&cache_max_age=7d" \
-H "x-api-key: $KEY"TypeScript
const query = new URLSearchParams({
query: 'ai agents',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/amazon/search?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 3 credits, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/amazon/search",
params={
"query": "ai agents",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or upstream_rate_limited. Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_blocked / upstream_schema_drift. Not charged |
| 504 | upstream_timeout. Not charged |
GET
/v1/amazon/shop1 creditcacheablebatchableAmazon Shop page
A creator's public Amazon storefront: their name, the product links the page exposes, and the storefront feed of idea lists (with Amazon's own item count), shoppable videos (id, title, thumbnail and attached ASINs) and shoppable photos. The first request needs no pageToken and already returns the videos embedded on the page. Pass pagination.cursor back as pageToken, unchanged, with the same shop URL for the next page; a page can carry lists, videos, photos or any mix. A continuation page carries the feed ONLY. Amazon serves it as a fragment with no profile markup, so every identity field (display name, bio, avatar) is null on page two onwards. ASINs are the products the storefront shows attached to an item, which for a long idea list is the first screenful rather than the whole list; itemCount is the true total.
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | yes | Storefront URL (https://www.amazon.com/shop/<handle>) or just the handle |
| pageToken | string | no | Opaque page token returned by a previous response for the same shop URL. Pass it back unchanged and do not infer the response type from its value. |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
Returns an object with platform, id, handle, displayName, bio, avatarUrl, bannerUrl, url, verified, followerCount, followingCount, postCount, viewCount, likeCount, isPrivate, isBusiness, category, location, externalLinks, createdAt, fetchedAt, storefront.
Fields
| Field | Type | Present | Description |
|---|---|---|---|
| platform | one of 32 strings | always | |
| id | string | always | The platform's own id for the account, such as a channel id or a numeric user id, always as a string. |
| handle | string | null | always | The account handle without the leading @. Null when the platform has no handles. |
| displayName | string | null | always | |
| bio | string | null | always | |
| avatarUrl | string | null | always | |
| bannerUrl | string | null | always | |
| url | string | null | always | |
| verified | boolean | null | always | Whether the platform shows a verification badge on the account. Null where the platform has no public badge or does not expose it. |
| followerCount | number | null | always | Followers, subscribers, or the platform's nearest equivalent. Null when the account hides the count or the platform does not expose it. |
| followingCount | number | null | always | |
| postCount | number | null | always | Posts, videos, tracks, repositories, or the platform's nearest equivalent that the account has published. |
| viewCount | number | null | always | Lifetime views across the account, where the platform exposes a total. |
| likeCount | number | null | may be absent | Total likes received across all of the creator's posts. Distinct from `viewCount`. Absent when the platform does not expose it. |
| isPrivate | boolean | null | always | |
| isBusiness | boolean | null | always | Whether the platform classifies the account as a business or organisation rather than a person or creator. Null where the platform draws no such line or does not expose it. On Facebook every Page counts, including Pages for public figures. |
| category | string | null | always | A label the platform attaches to the account, such as a business category, a genre or an account type. What it holds varies by platform. |
| location | string | null | always | Location as the platform shows it: a city, a country, a region code or an address, depending on the platform. |
| externalLinks | string[] | always | Links the account lists on its profile, such as a website or other social accounts. |
| createdAt | string | null | always | When the account was created. Usually an ISO 8601 timestamp; some platforms expose only the date as shown on the profile. |
| fetchedAt | string | always | When this record was fetched from the platform, as an ISO 8601 timestamp. A cached response keeps the time of the original fetch. |
| storefront | object | always | |
| storefront.lists | object[] | always | |
| storefront.lists[].id | string | always | |
| storefront.lists[].title | string | null | always | |
| storefront.lists[].url | string | null | always | |
| storefront.lists[].itemCount | number | null | always | |
| storefront.lists[].thumbnailUrl | string | null | always | |
| storefront.videos | object[] | always | |
| storefront.videos[].id | string | always | |
| storefront.videos[].title | string | null | always | |
| storefront.videos[].url | string | null | always | |
| storefront.videos[].thumbnailUrl | string | null | always | |
| storefront.videos[].asins | string[] | always | |
| storefront.photos | object[] | always | |
| storefront.photos[].id | string | always | |
| storefront.photos[].url | string | null | always | |
| storefront.photos[].thumbnailUrl | string | null | always | |
| storefront.photos[].asins | string[] | always |
curl
curl "$API/v1/amazon/shop?url=8XkPqR2nLvE&cache_max_age=7d" \
-H "x-api-key: $KEY"TypeScript
const query = new URLSearchParams({
url: '8XkPqR2nLvE',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/amazon/shop?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/amazon/shop",
params={
"url": "8XkPqR2nLvE",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or upstream_rate_limited. Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_blocked / upstream_schema_drift. Not charged |
| 504 | upstream_timeout. Not charged |
Questions
- How much does the Amazon API cost?
- Calls cost 1–3 credits each. Every endpoint is cacheable, and a cache hit costs nothing. A failed request and an empty result are both free, on every endpoint.
- Does the Amazon API need a login or cookies?
- No. Every endpoint reads public, logged-out pages only — no account, no cookies, no session. An API key identifies your own TrueScrape account and nothing else.
- Can I fetch many Amazon targets in one request?
- Yes. 4 of 4 are batchable: one POST to /v1/jobs/batch takes many targets and returns a job id to poll.
- Can I watch Amazon endpoints for changes?
- Yes, 3 of 4. A subscription polls on your schedule and fires your webhook only when the content changed; the rest carry x-subscribable: false in the spec.