{ "openapi": "3.1.0", "info": { "title": "Amazon Product API", "version": "1.0.0", "description": "Current Amazon prices, product details and keyword search across 20 marketplaces, exposed through FetchLayer as structured JSON." }, "servers": [ { "url": "https://api.fetchlayer.dev/amazon" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/price-check": { "post": { "operationId": "price-check", "tags": [ "Prices" ], "summary": "Check current prices for up to 20 products", "description": "Send up to 20 ASINs or product URLs and get back the current price of each, in the marketplace’s own currency, for a delivery postal code. This is the route built for price monitoring. In fast mode, the default, a whole batch is priced for a small fraction of what reading each product page costs; seller and stock status are included only where they come at no extra cost. Full mode reads every product page and returns seller and stock status for every product. Both modes return the same price. One product failing never fails the batch: it comes back with status failed, and only when no product at all could be retrieved is the call an error. Amazon shows current prices only — to build a price history, call this on a schedule. Billing: each product that gets a definitive result — a price, or a status such as out of stock, ended, unavailable or not found — counts as one request, so pricing 20 products bills 20. Products that fail on our side (blocked, timed out, not reached) are not billed, and duplicates count once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asins": { "type": "array", "items": { "type": "string" }, "description": "1–20 products, each an ASIN or an Amazon product URL, all on the same marketplace." }, "mode": { "type": "string", "description": "fast: price, currency, status and hasFeaturedOffer for every product, in the fewest page loads. full: also availability and seller for every product, with a full product-page load per product.", "example": "fast" }, "marketplace": { "type": "string", "description": "Amazon marketplace as its domain suffix: com, co.uk, de, fr, it, es, nl, com.be, se, pl, ca, com.mx, com.br, com.au, co.jp, in, sg, com.tr, ae, sa. amazon.co.uk and uk are accepted too. A product URL carries its own marketplace, and naming a different one here is a 400.", "example": "com" }, "postalCode": { "type": "string", "description": "The delivery postal code prices and stock are quoted for. Defaults to a central postal code in the marketplace's country: 10001 for com, SW1A 1AA for co.uk, 10115 for de." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "asins" ] }, "examples": { "default": { "value": { "asins": [ "B09B8V1LZ3", "B00FLYWNYQ", "B07S98411N" ], "marketplace": "com" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pagesScraped": { "type": "number", "description": "Products that received a definitive result. Each counts as one request against your plan; failed products and duplicates do not." }, "marketplace": { "type": "string", "description": "The Amazon marketplace, as its domain suffix." }, "deliveryLocation": { "type": "object", "additionalProperties": true, "description": "Where the prices apply: postalCode and Amazon’s own label for it. postalCode is null when a price could not be quoted for the postal code you asked for — notes says so." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — a price quoted for a different location than asked for, a filter that could not be applied, products to retry. Read it on every call." }, "transport": { "type": "string", "description": "The source this data came from. Always \"amazon\"." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "mode": { "type": "string", "description": "The mode this batch was priced in." }, "requested": { "type": "number", "description": "Products in the request." }, "succeeded": { "type": "number", "description": "Products that came back ok or unavailable." }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "asin": { "type": "string", "description": "The product’s ASIN." }, "url": { "type": "string", "description": "The product page URL." }, "status": { "type": "string", "description": "ok — a current offer was found. unavailable — the product exists but has no current offer. not_found — no such product on this marketplace. failed — this one product could not be retrieved; retry it." }, "price": { "type": "object", "additionalProperties": true, "description": "{ amount, currency, display } in the currency the page actually quoted, or null." }, "availability": { "type": "object", "additionalProperties": true, "description": "{ status, text }. status is one of in_stock, low_stock, out_of_stock, undeliverable, preorder, unknown — undeliverable means not offered to the delivery location, not sold out. null when not included (fast mode) or not shown." }, "seller": { "type": "object", "additionalProperties": true, "description": "{ name, id } of the featured offer’s seller. Usually null in fast mode." }, "hasFeaturedOffer": { "type": "boolean", "description": "Whether there is an offer that Add to Cart buys." } } }, "description": "One entry per requested product, in request order." } }, "additionalProperties": false }, "examples": { "default": { "value": { "marketplace": "com", "mode": "fast", "deliveryLocation": { "postalCode": "10001", "label": "New York 10001" }, "requested": 3, "succeeded": 3, "items": [ { "asin": "B09B8V1LZ3", "url": "https://www.amazon.com/dp/B09B8V1LZ3", "status": "ok", "price": { "amount": 79.99, "currency": "USD", "display": "$79.99" }, "availability": null, "seller": null, "hasFeaturedOffer": true }, { "asin": "B00FLYWNYQ", "url": "https://www.amazon.com/dp/B00FLYWNYQ", "status": "ok", "price": { "amount": 109.99, "currency": "USD", "display": "$109.99" }, "availability": null, "seller": null, "hasFeaturedOffer": true }, { "asin": "B07S98411N", "url": "https://www.amazon.com/dp/B07S98411N", "status": "ok", "price": { "amount": 89.99, "currency": "USD", "display": "$89.99" }, "availability": null, "seller": null, "hasFeaturedOffer": true } ], "notes": [ "Seller and stock status are not included for every product in fast mode; use mode \"full\" for them" ], "transport": "amazon", "scrapedAt": "2026-09-12T22:08:04.231Z" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/product-details": { "post": { "operationId": "product-details", "tags": [ "Products" ], "summary": "Get one product in full", "description": "Read one Amazon product from its ASIN or product URL: title and brand, the featured offer’s price, the crossed-out list price and savings percent when it is discounted, availability and seller, the aggregate star rating and how many ratings it is based on, every gallery image at its largest size, the About this item bullets, the category breadcrumb, and the whole variation family — the parent ASIN, what the variations differ by, and every size, colour or style with its own ASIN. Prices are quoted for the delivery location the response names. Individual customer reviews are not part of this API; rating is the aggregate only. A product that does not exist on the marketplace is a 404.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "description": "An ASIN (with marketplace), or an Amazon product URL on any supported marketplace." }, "marketplace": { "type": "string", "description": "Amazon marketplace as its domain suffix: com, co.uk, de, fr, it, es, nl, com.be, se, pl, ca, com.mx, com.br, com.au, co.jp, in, sg, com.tr, ae, sa. amazon.co.uk and uk are accepted too. A product URL carries its own marketplace, and naming a different one here is a 400.", "example": "com" }, "postalCode": { "type": "string", "description": "The delivery postal code prices and stock are quoted for. Defaults to a central postal code in the marketplace's country: 10001 for com, SW1A 1AA for co.uk, 10115 for de." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "product" ] }, "examples": { "default": { "value": { "product": "B09B8V1LZ3" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "marketplace": { "type": "string", "description": "The Amazon marketplace, as its domain suffix." }, "deliveryLocation": { "type": "object", "additionalProperties": true, "description": "Where the prices apply: postalCode and Amazon’s own label for it. postalCode is null when a price could not be quoted for the postal code you asked for — notes says so." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — a price quoted for a different location than asked for, a filter that could not be applied, products to retry. Read it on every call." }, "transport": { "type": "string", "description": "The source this data came from. Always \"amazon\"." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "asin": { "type": "string", "description": "The product’s ASIN." }, "url": { "type": "string", "description": "The product page URL." }, "title": { "type": "string", "description": "The product title as the page shows it." }, "brand": { "type": "string", "description": "The brand as the page shows it." }, "price": { "type": "object", "additionalProperties": true, "description": "The featured offer’s price: { amount, currency, display } in the currency the page actually quoted, or null." }, "listPrice": { "type": "object", "additionalProperties": true, "description": "The crossed-out reference price, only when it is higher than price. A \"was\" price equal to the current price is left out." }, "savingsPercent": { "type": "number", "description": "The percentage off listPrice, as the page states it." }, "availability": { "type": "object", "additionalProperties": true, "description": "{ status, text } — status is one of in_stock, low_stock, out_of_stock, undeliverable, preorder, unknown. Branch on status, not on Amazon’s wording in text." }, "seller": { "type": "object", "additionalProperties": true, "description": "{ name, id } of the featured offer’s seller." }, "hasFeaturedOffer": { "type": "boolean", "description": "Whether there is an offer that Add to Cart buys." }, "rating": { "type": "object", "additionalProperties": true, "description": "{ average, count } — the aggregate star rating and how many ratings it is based on." }, "images": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Every gallery image at its largest size, each { url, variant }. MAIN is the lead image." }, "features": { "type": "array", "items": { "type": "string" }, "description": "The About this item bullets." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "The category breadcrumb, broadest first. Empty when the page shows none." }, "parentAsin": { "type": "string", "description": "The listing this family of variations belongs to." }, "variationDimensions": { "type": "array", "items": { "type": "string" }, "description": "What the variations differ by, for example [\"Size\"] or [\"Color\", \"Style Name\"]." }, "variations": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Every size, colour or style in the family: { asin, values, selected }, where selected marks the product you asked for." } }, "additionalProperties": false }, "examples": { "default": { "value": { "asin": "B09B8V1LZ3", "url": "https://www.amazon.com/dp/B09B8V1LZ3", "marketplace": "com", "title": "Amazon Echo Dot (newest model) - Vibrant sounding speaker, Designed for Alexa+, Great for bedrooms, dining rooms and offices, Charcoal", "brand": "Amazon", "price": { "amount": 79.99, "currency": "USD", "display": "$79.99" }, "listPrice": null, "savingsPercent": null, "availability": { "status": "in_stock", "text": "In Stock" }, "seller": { "name": "Amazon.com", "id": "ATVPDKIKX0DER" }, "hasFeaturedOffer": true, "rating": { "average": 4.7, "count": 199523 }, "images": [ { "url": "https://m.media-amazon.com/images/I/71hNp8d9WvL._AC_SL1500_.jpg", "variant": "MAIN" } ], "features": [ "Your favorite music and content – Play music, audiobooks, and podcasts from Amazon Music, Apple Music, Spotify and others or via Bluetooth throughout your home." ], "categories": [], "parentAsin": "B0BF73CTQF", "variationDimensions": [ "Color", "Configuration" ], "variations": [ { "asin": "B09B94RL1R", "values": [ "Glacier White", "Device only" ], "selected": false }, { "asin": "B09B8V1LZ3", "values": [ "Charcoal", "Device only" ], "selected": true } ], "deliveryLocation": { "postalCode": "10001", "label": "New York 10001" }, "notes": [], "transport": "amazon", "scrapedAt": "2026-09-12T22:17:10.176Z" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/search-products": { "post": { "operationId": "search-products", "tags": [ "Products" ], "summary": "Search products by keyword", "description": "Search an Amazon marketplace by keyword and get each result’s ASIN, title, URL, current price and list price, aggregate star rating and rating count, thumbnail, whether it is a sponsored placement, and where it appeared. Filter by department, price range and minimum rating, and sort by relevance, price, rating, newest or bestsellers. The response reports appliedFilters — the filters that were actually applied, which can differ from the ones requested — and Amazon’s own totalResults estimate. Amazon shows at most 20 result pages for any search; to reach further, narrow the search. The ASINs a search returns are what price-check and product-details take.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Search keywords." }, "department": { "type": "string", "description": "A department id as it appears in Amazon search URLs, for example electronics, fashion or digital-text." }, "minPrice": { "type": "number", "description": "Lowest price, in the marketplace’s currency. Amazon applies it to the regular price, so a discounted product can show a price just below it." }, "maxPrice": { "type": "number", "description": "Highest price, in the marketplace’s currency." }, "minRating": { "type": "number", "description": "Only products rated at least this many stars (1–4). Amazon typically offers only 4; appliedFilters.minRating is null, with a note, when the threshold you asked for is not offered." }, "sortBy": { "type": "string", "description": "relevance, price_asc, price_desc, rating, newest or bestsellers.", "example": "relevance" }, "limit": { "type": "number", "description": "Maximum products returned (max 1000), or -1 for no limit.", "example": "48" }, "pages": { "type": "number", "description": "Result pages to collect in one request (max 20), or -1 for as many as Amazon shows. Each page counts as one request against your plan.", "example": "1" }, "cursor": { "type": "string", "description": "A previous response’s nextCursor, sent with the same query." }, "marketplace": { "type": "string", "description": "Amazon marketplace as its domain suffix: com, co.uk, de, fr, it, es, nl, com.be, se, pl, ca, com.mx, com.br, com.au, co.jp, in, sg, com.tr, ae, sa. amazon.co.uk and uk are accepted too. A product URL carries its own marketplace, and naming a different one here is a 400.", "example": "com" }, "postalCode": { "type": "string", "description": "The delivery postal code prices and stock are quoted for. Defaults to a central postal code in the marketplace's country: 10001 for com, SW1A 1AA for co.uk, 10115 for de." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "mechanical keyboard", "maxPrice": 100, "marketplace": "com" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "marketplace": { "type": "string", "description": "The Amazon marketplace, as its domain suffix." }, "deliveryLocation": { "type": "object", "additionalProperties": true, "description": "Where the prices apply: postalCode and Amazon’s own label for it. postalCode is null when a price could not be quoted for the postal code you asked for — notes says so." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — a price quoted for a different location than asked for, a filter that could not be applied, products to retry. Read it on every call." }, "transport": { "type": "string", "description": "The source this data came from. Always \"amazon\"." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "query": { "type": "string", "description": "The search this response answers." }, "totalResults": { "type": "number", "description": "Amazon’s own estimate of how many products match." }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "asin": { "type": "string", "description": "The product’s ASIN — what price-check and product-details take." }, "title": { "type": "string", "description": "The product title." }, "url": { "type": "string", "description": "The product page URL." }, "price": { "type": "object", "additionalProperties": true, "description": "{ amount, currency, display } in the currency the page actually quoted, or null. Null when the product has no featured offer — call price-check or product-details to see why." }, "listPrice": { "type": "object", "additionalProperties": true, "description": "The crossed-out reference price, when shown." }, "rating": { "type": "object", "additionalProperties": true, "description": "{ average, count } — the aggregate star rating." }, "image": { "type": "string", "description": "Thumbnail URL." }, "sponsored": { "type": "boolean", "description": "A paid placement rather than an organic result." }, "position": { "type": "number", "description": "Position on the results page it came from." }, "page": { "type": "number", "description": "The results page it came from." } } }, "description": "The matching products, in the order Amazon showed them." }, "productCount": { "type": "number", "description": "Products in this response." }, "pagesScraped": { "type": "number", "description": "Result pages collected. Each page counts as one request against your plan." }, "hasNextPage": { "type": "boolean", "description": "Whether Amazon shows another page." }, "nextCursor": { "type": "string", "description": "Pass back as cursor, with the same query, to continue. null when there is nothing further." }, "appliedFilters": { "type": "object", "additionalProperties": true, "description": "The filters actually applied: department, minPrice, maxPrice, minRating and sortBy. Compare with your request." } }, "additionalProperties": false }, "examples": { "default": { "value": { "query": "mechanical keyboard", "marketplace": "com", "totalResults": 13601, "products": [ { "asin": "B0CLLHSWRL", "title": "AULA F99 Wireless Mechanical Keyboard, Tri-Mode BT5.0/2.4GHz/USB-C Hot Swappable Custom Keyboard", "url": "https://www.amazon.com/dp/B0CLLHSWRL", "price": { "amount": 68.99, "currency": "USD", "display": "$68.99" }, "listPrice": { "amount": 78.84, "currency": "USD", "display": "$78.84" }, "rating": { "average": 4.5, "count": 3147 }, "image": "https://m.media-amazon.com/images/I/61mB8mL33pL._AC_UY218_.jpg", "sponsored": true, "position": 1, "page": 1 }, { "asin": "B0CQ2L9PCB", "title": "RK ROYAL KLUDGE S98 Wireless Mechanical Keyboard w/Smart Display & Knob", "url": "https://www.amazon.com/dp/B0CQ2L9PCB", "price": { "amount": 74.99, "currency": "USD", "display": "$74.99" }, "listPrice": { "amount": 89.99, "currency": "USD", "display": "$89.99" }, "rating": { "average": 4.4, "count": 1666 }, "image": "https://m.media-amazon.com/images/I/61g03L1eB1L._AC_UY218_.jpg", "sponsored": true, "position": 2, "page": 1 } ], "productCount": 19, "pagesScraped": 1, "hasNextPage": true, "nextCursor": "eyJ2IjoxLCJtYXJrZXRw…", "appliedFilters": { "department": null, "minPrice": null, "maxPrice": 100, "minRating": null, "sortBy": "relevance" }, "deliveryLocation": { "postalCode": "10001", "label": "New York 10001" }, "notes": [], "transport": "amazon", "scrapedAt": "2026-09-12T22:18:21.972Z" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/resolve-url": { "post": { "operationId": "resolve-url", "tags": [ "Utility" ], "summary": "Parse an Amazon URL", "description": "Turn any Amazon URL into the structured input it encodes, without contacting Amazon. A product URL in any of its common shapes (/dp/, /gp/product/, /gp/aw/d/, with or without a slug and tracking parameters) comes back as its marketplace and ASIN; a search URL comes back as its query, department, price bounds, sort order and page. Both come with a clean canonical URL. Parsing a URL does not consume a credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Any Amazon URL, to be parsed into structured input." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "url" ] }, "examples": { "default": { "value": { "url": "https://www.amazon.com/Instant-Pot-Multi-Use-Programmable-Pressure/dp/B00FLYWNYQ/ref=sr_1_3?keywords=instant+pot" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "What the URL points at: product, search, or unknown." }, "marketplace": { "type": "string", "description": "The marketplace, for example com. null for a URL that is not on a supported Amazon marketplace." }, "asin": { "type": "string", "description": "Present when kind is product — pass it to price-check or product-details." }, "query": { "type": "string", "description": "Present when kind is search — pass it to search-products." }, "department": { "type": "string", "description": "Department carried in a search URL." }, "minPrice": { "type": "number", "description": "Lower price bound carried in a search URL." }, "maxPrice": { "type": "number", "description": "Upper price bound carried in a search URL." }, "sortBy": { "type": "string", "description": "Sort order carried in a search URL." }, "page": { "type": "number", "description": "Page number carried in a search URL." }, "canonicalUrl": { "type": "string", "description": "A clean URL for the product or search." } }, "additionalProperties": false }, "examples": { "default": { "value": { "kind": "product", "marketplace": "com", "asin": "B00FLYWNYQ", "query": null, "department": null, "minPrice": null, "maxPrice": null, "sortBy": null, "page": null, "canonicalUrl": "https://www.amazon.com/dp/B00FLYWNYQ" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } } } }