{ "openapi": "3.1.0", "info": { "title": "ScrapeBadger Amazon API", "version": "1.0.0", "description": "Amazon marketplace scraping API for searching products, fetching product details, offers, reviews, listings, sellers, and reference data across 20 marketplaces." }, "servers": [ { "url": "https://scrapebadger.com", "description": "Production" } ], "security": [ { "apiKeyAuth": [] } ], "paths": { "/v1/amazon/search": { "get": { "operationId": "searchAmazonProducts", "summary": "Search Products", "description": "Search the Amazon catalog with filters and sorting.", "tags": [ "Amazon Search" ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search keywords." }, { "name": "domain", "in": "query", "schema": { "type": "string", "default": "com" }, "description": "Amazon marketplace TLD or code (com, co.uk, de, fr, ...)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 20 }, "description": "Page number for paginated results." }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": [ "relevance", "price_low_to_high", "price_high_to_low", "avg_review", "newest" ] }, "description": "Sort order for results." }, { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Department/category alias to scope the search (the i= parameter)." }, { "name": "min_price", "in": "query", "schema": { "type": "number", "minimum": 0 }, "description": "Minimum price filter in the marketplace's local currency." }, { "name": "max_price", "in": "query", "schema": { "type": "number", "minimum": 0 }, "description": "Maximum price filter in the marketplace's local currency." }, { "name": "zip", "in": "query", "schema": { "type": "string" }, "description": "Delivery postal/zip code for localized pricing." }, { "name": "language", "in": "query", "schema": { "type": "string" }, "description": "Locale for results, e.g. en_US, fr_FR." } ], "responses": { "200": { "description": "Successful search", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query that was executed." }, "domain": { "type": "string", "description": "Marketplace domain that was searched." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "query": "wireless earbuds", "domain": "com", "results": [ { "position": 1, "asin": "B0CHWRXH8B", "title": "Bose QuietComfort Ultra Wireless Earbuds", "link": "https://www.amazon.com/dp/B0CHWRXH8B", "image": "https://m.media-amazon.com/images/I/61abc123.jpg", "price": { "value": 249, "currency": "USD", "symbol": "$", "raw": "$249.00" }, "list_price": { "value": 299, "currency": "USD", "symbol": "$", "raw": "$299.00" }, "unit_price": null, "rating": 4.4, "ratings_total": 12480, "is_prime": true, "is_sponsored": false, "is_amazons_choice": true, "is_best_seller": false, "bought_past_month": "5K+ bought in past month", "coupon": null, "availability": "In Stock" } ], "pagination": { "current_page": 1, "total_pages": 20, "total_results": 480 } } } } } } } }, "/v1/amazon/autocomplete": { "get": { "operationId": "amazonAutocomplete", "summary": "Keyword Suggestions", "description": "Get Amazon search autocomplete suggestions for keyword research.", "tags": [ "Amazon Search" ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Partial search term to expand into suggestions." }, { "name": "domain", "in": "query", "schema": { "type": "string", "default": "com" }, "description": "Amazon marketplace TLD or code (com, co.uk, de, ...)." } ], "responses": { "200": { "description": "Autocomplete suggestions", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "domain": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Suggested search phrase." }, "alias": { "type": "string", "nullable": true, "description": "Department alias the suggestion is scoped to, if any." } } } } } }, "example": { "query": "wireless ear", "domain": "com", "suggestions": [ { "value": "wireless earbuds", "alias": "aps" }, { "value": "wireless earbuds bluetooth", "alias": "aps" }, { "value": "wireless earphones", "alias": "electronics" } ] } } } } } } }, "/v1/amazon/products/{asin}": { "get": { "operationId": "getAmazonProduct", "summary": "Get Product Detail", "description": "Full product detail by ASIN (price, variants, badges, buybox, ranks, ...).", "tags": [ "Amazon Products" ], "parameters": [ { "name": "asin", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Amazon Standard Identification Number (ASIN) of the product." }, { "name": "domain", "in": "query", "schema": { "type": "string", "default": "com" }, "description": "Amazon marketplace TLD or code (com, co.uk, de, ...)." }, { "name": "zip", "in": "query", "schema": { "type": "string" }, "description": "Delivery postal/zip code for a localized buybox." }, { "name": "language", "in": "query", "schema": { "type": "string" }, "description": "Locale for the product page, e.g. en_US, de_DE." } ], "responses": { "200": { "description": "Product detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "product": { "$ref": "#/components/schemas/Product" } } }, "example": { "domain": "com", "product": { "asin": "B08N5WRWNW", "parent_asin": "B08N5M9NMG", "title": "Echo Dot (4th Gen) Smart speaker with Alexa", "link": "https://www.amazon.com/dp/B08N5WRWNW", "brand": "Amazon", "manufacturer": "Amazon", "model_number": "B7W64E", "price": { "value": 49.99, "currency": "USD", "symbol": "$", "raw": "$49.99" }, "list_price": { "value": 59.99, "currency": "USD", "symbol": "$", "raw": "$59.99" }, "savings_amount": { "value": 10, "currency": "USD", "symbol": "$", "raw": "$10.00" }, "discount_percent": 17, "rating": 4.7, "ratings_total": 184231, "rating_breakdown": { "five_star": 78, "four_star": 13, "three_star": 4, "two_star": 2, "one_star": 3 }, "bought_past_month": "20K+ bought in past month", "in_stock": true, "availability": "In Stock", "feature_bullets": [ "Meet the Echo Dot - Our most popular smart speaker with a fabric design.", "Voice control your entertainment - Stream songs from Amazon Music, Apple Music, Spotify." ], "description": "Echo Dot is our most compact smart speaker that fits perfectly into small spaces.", "main_image": "https://m.media-amazon.com/images/I/714Rdc+abc.jpg", "images": [ "https://m.media-amazon.com/images/I/714Rdc+abc.jpg", "https://m.media-amazon.com/images/I/61abc+def.jpg" ], "images_count": 6, "videos": [], "videos_count": 0, "has_aplus_content": true, "variants": [ { "asin": "B08N5WRWNW", "attributes": { "Color": "Charcoal" }, "price": { "value": 49.99, "currency": "USD", "symbol": "$", "raw": "$49.99" }, "is_current": true }, { "asin": "B08N5KWB9H", "attributes": { "Color": "Glacier White" }, "price": { "value": 49.99, "currency": "USD", "symbol": "$", "raw": "$49.99" }, "is_current": false } ], "variant_asins": [ "B08N5WRWNW", "B08N5KWB9H" ], "categories": [ { "name": "Electronics", "link": "https://www.amazon.com/electronics", "category_id": "172282" }, { "name": "Smart Home", "link": "https://www.amazon.com/smart-home", "category_id": "6563140011" } ], "bestsellers_rank": [ { "rank": 334, "category": "Electronics", "link": "https://www.amazon.com/gp/bestsellers/electronics" }, { "rank": 1, "category": "Smart Speakers", "link": "https://www.amazon.com/gp/bestsellers/electronics/smart-speakers" } ], "attributes": { "Connectivity Technology": "Wi-Fi, Bluetooth" }, "specifications": { "Item Weight": "12 ounces", "Product Dimensions": "3.9 x 3.9 x 3.5 inches" }, "dimensions": "3.9 x 3.9 x 3.5 inches", "weight": "12 ounces", "first_available": "October 22, 2020", "country_of_origin": "China", "buybox": { "seller_name": "Amazon.com", "seller_id": "ATVPDKIKX0DER", "price": { "value": 49.99, "currency": "USD", "symbol": "$", "raw": "$49.99" }, "fulfillment": "Amazon" }, "sold_by": "Amazon.com", "ships_from": "Amazon.com", "fulfilled_by": "Amazon", "is_amazon_seller": true, "badges": { "amazons_choice": true, "amazons_choice_keyword": "smart speaker", "best_seller": false, "prime": true, "climate_pledge_friendly": true }, "coupon": { "text": "Save 5% with coupon", "discount": "5%" }, "deal": null, "delivery": { "message": "FREE delivery Tomorrow", "date": "2026-06-04", "is_free": true }, "frequently_bought_together": [ "B07FZ8S74R" ], "also_bought": [ "B07FZ8S74R", "B08C1W5N87" ], "answered_questions": 1024, "top_reviews": [ { "id": "R1ABCDEF123456", "title": "Great little speaker", "body": "Sound quality is excellent for the size.", "rating": 5, "verified_purchase": true } ], "scraped_utc": 1780531200, "scraped_at": "2026-06-03T12:00:00Z" } } } } } } } }, "/v1/amazon/products/{asin}/offers": { "get": { "operationId": "getAmazonOffers", "summary": "Get Offers", "description": "All third-party offers for an ASIN, including the Buy Box winner.", "tags": [ "Amazon Products" ], "parameters": [ { "name": "asin", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ASIN of the product to list offers for." }, { "name": "domain", "in": "query", "schema": { "type": "string", "default": "com" }, "description": "Amazon marketplace TLD or code (com, co.uk, de, ...)." }, { "name": "zip", "in": "query", "schema": { "type": "string" }, "description": "Delivery postal/zip code for localized offers and delivery estimates." } ], "responses": { "200": { "description": "Offer listing", "content": { "application/json": { "schema": { "type": "object", "properties": { "asin": { "type": "string" }, "domain": { "type": "string" }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } } } }, "example": { "asin": "B08N5WRWNW", "domain": "com", "offers": [ { "position": 1, "seller": { "name": "Amazon.com", "id": "ATVPDKIKX0DER", "link": "https://www.amazon.com/sp?seller=ATVPDKIKX0DER", "rating": 4.7, "ratings_total": 1284000, "ratings_percentage_positive": 96 }, "price": { "value": 49.99, "currency": "USD", "symbol": "$", "raw": "$49.99" }, "condition": { "is_new": true, "title": "New", "comments": null }, "delivery": { "is_free": true, "fulfilled_by_amazon": true, "date": "2026-06-04", "price": null }, "buybox_winner": true, "is_prime": true, "minimum_order_quantity": 1, "maximum_order_quantity": 30 }, { "position": 2, "seller": { "name": "TechDeals Store", "id": "A1B2C3D4E5F6G7", "link": "https://www.amazon.com/sp?seller=A1B2C3D4E5F6G7", "rating": 4.6, "ratings_total": 8421, "ratings_percentage_positive": 94 }, "price": { "value": 47.5, "currency": "USD", "symbol": "$", "raw": "$47.50" }, "condition": { "is_new": true, "title": "New", "comments": null }, "delivery": { "is_free": false, "fulfilled_by_amazon": false, "date": "2026-06-08", "price": { "value": 4.99, "currency": "USD", "symbol": "$", "raw": "$4.99" } }, "buybox_winner": false, "is_prime": false, "minimum_order_quantity": 1, "maximum_order_quantity": 10 } ] } } } } } } }, "/v1/amazon/products/{asin}/reviews": { "get": { "operationId": "getAmazonReviews", "summary": "Get Reviews", "description": "Customer reviews for an ASIN (featured + paginated, with filters).", "tags": [ "Amazon Products" ], "parameters": [ { "name": "asin", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ASIN of the product to fetch reviews for." }, { "name": "domain", "in": "query", "schema": { "type": "string", "default": "com" }, "description": "Amazon marketplace TLD or code (com, co.uk, de, ...)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number for paginated reviews." }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "helpful", "enum": [ "helpful", "recent" ] }, "description": "Sort order for reviews." }, { "name": "star", "in": "query", "schema": { "type": "string", "enum": [ "one_star", "two_star", "three_star", "four_star", "five_star", "positive", "critical" ] }, "description": "Filter reviews by star rating or sentiment." }, { "name": "verified_only", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Only return reviews from verified purchases." }, { "name": "media_only", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Only return reviews that include images or video." } ], "responses": { "200": { "description": "Product reviews", "content": { "application/json": { "schema": { "type": "object", "properties": { "asin": { "type": "string" }, "domain": { "type": "string" }, "rating": { "type": "number", "description": "Overall average product rating." }, "ratings_total": { "type": "integer", "description": "Total number of ratings for the product." }, "rating_breakdown": { "type": "object", "properties": { "five_star": { "type": "integer" }, "four_star": { "type": "integer" }, "three_star": { "type": "integer" }, "two_star": { "type": "integer" }, "one_star": { "type": "integer" } } }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "asin": "B08N5WRWNW", "domain": "com", "rating": 4.7, "ratings_total": 184231, "rating_breakdown": { "five_star": 78, "four_star": 13, "three_star": 4, "two_star": 2, "one_star": 3 }, "reviews": [ { "id": "R1ABCDEF123456", "title": "Great little speaker", "body": "Sound quality is excellent for the size. Setup was quick and Alexa is responsive.", "rating": 5, "date_raw": "Reviewed in the United States on May 28, 2026", "date_utc": 1780012800, "date_at": "2026-05-28T00:00:00Z", "review_country": "United States", "is_global_review": false, "profile": { "name": "Jane D.", "link": "https://www.amazon.com/gp/profile/amzn1.account.ABC", "id": "amzn1.account.ABC", "image": "https://m.media-amazon.com/images/S/amazon-avatars/abc.png" }, "verified_purchase": true, "vine_program": false, "helpful_votes": 42, "variant": "Color: Charcoal", "images": [ "https://m.media-amazon.com/images/I/71review1.jpg" ] } ], "pagination": { "current_page": 1, "total_pages": 100, "total_results": 1000 } } } } } } } }, "/v1/amazon/bestsellers": { "get": { "operationId": "getAmazonBestsellers", "summary": "Bestsellers", "description": "Top-selling products for a category (browse node).", "tags": [ "Amazon Listings" ], "parameters": [ { "name": "domain", "in": "query", "schema": { "type": "string", "default": "com" }, "description": "Amazon marketplace TLD or code (com, co.uk, de, ...)." }, { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Bestsellers node id or category slug (e.g. electronics)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 2 }, "description": "Page number (each page covers 50 ranks; max 2)." } ], "responses": { "200": { "description": "Bestsellers list", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "category": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Bestseller" } } } }, "example": { "domain": "com", "category": "electronics", "results": [ { "rank": 1, "position": 1, "asin": "B09B8V1LZ3", "title": "Apple AirTag", "link": "https://www.amazon.com/dp/B09B8V1LZ3", "image": "https://m.media-amazon.com/images/I/71abc.jpg", "rating": 4.7, "ratings_total": 412300, "price": { "value": 24, "currency": "USD", "symbol": "$", "raw": "$24.00" } } ] } } } } } } }, "/v1/amazon/new-releases": { "get": { "operationId": "getAmazonNewReleases", "summary": "New Releases", "description": "Newly released products for a category (browse node).", "tags": [ "Amazon Listings" ], "parameters": [ { "name": "domain", "in": "query", "schema": { "type": "string", "default": "com" }, "description": "Amazon marketplace TLD or code (com, co.uk, de, ...)." }, { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "New-releases node id or category slug." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 2 }, "description": "Page number (each page covers 50 ranks; max 2)." } ], "responses": { "200": { "description": "New releases list", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "category": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Bestseller" } } } }, "example": { "domain": "com", "category": "electronics", "results": [ { "rank": 1, "position": 1, "asin": "B0CX23V2ZK", "title": "Anker Prime Power Bank (2026)", "link": "https://www.amazon.com/dp/B0CX23V2ZK", "image": "https://m.media-amazon.com/images/I/61new.jpg", "rating": 4.6, "ratings_total": 842, "price": { "value": 129.99, "currency": "USD", "symbol": "$", "raw": "$129.99" } } ] } } } } } } }, "/v1/amazon/deals": { "get": { "operationId": "getAmazonDeals", "summary": "Today's Deals", "description": "Current Amazon deals (lightning deals, best deals).", "tags": [ "Amazon Listings" ], "parameters": [ { "name": "domain", "in": "query", "schema": { "type": "string", "default": "com" }, "description": "Amazon marketplace TLD or code (com, co.uk, de, ...)." }, { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Category alias to scope the deals feed." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number for paginated deals." } ], "responses": { "200": { "description": "Deals list", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "category": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } } } }, "example": { "domain": "com", "category": null, "results": [ { "position": 1, "asin": "B0C7KMR3T5", "title": "Sony WH-1000XM5 Wireless Headphones", "link": "https://www.amazon.com/dp/B0C7KMR3T5", "image": "https://m.media-amazon.com/images/I/61deal.jpg", "deal_price": { "value": 298, "currency": "USD", "symbol": "$", "raw": "$298.00" }, "list_price": { "value": 399.99, "currency": "USD", "symbol": "$", "raw": "$399.99" }, "discount_percent": 25, "deal_type": "Best Deal", "is_lightning_deal": false, "badge": "Limited time deal", "ends_at_utc": null, "ends_at": null } ] } } } } } } }, "/v1/amazon/category": { "get": { "operationId": "browseAmazonCategory", "summary": "Browse Category", "description": "List products within an Amazon browse-node category.", "tags": [ "Amazon Listings" ], "parameters": [ { "name": "node", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Amazon browse-node id to list products from." }, { "name": "domain", "in": "query", "schema": { "type": "string", "default": "com" }, "description": "Amazon marketplace TLD or code (com, co.uk, de, ...)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 20 }, "description": "Page number for paginated results." }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": [ "relevance", "price_low_to_high", "price_high_to_low", "avg_review", "newest" ] }, "description": "Sort order for results." } ], "responses": { "200": { "description": "Category product listing", "content": { "application/json": { "schema": { "type": "object", "properties": { "node": { "type": "string" }, "domain": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "node": "172282", "domain": "com", "results": [ { "position": 1, "asin": "B0CHWRXH8B", "title": "Bose QuietComfort Ultra Wireless Earbuds", "link": "https://www.amazon.com/dp/B0CHWRXH8B", "image": "https://m.media-amazon.com/images/I/61abc123.jpg", "price": { "value": 249, "currency": "USD", "symbol": "$", "raw": "$249.00" }, "list_price": null, "unit_price": null, "rating": 4.4, "ratings_total": 12480, "is_prime": true, "is_sponsored": false, "is_amazons_choice": false, "is_best_seller": true, "bought_past_month": null, "coupon": null, "availability": "In Stock" } ], "pagination": { "current_page": 1, "total_pages": 20, "total_results": 660 } } } } } } } }, "/v1/amazon/sellers/{seller_id}": { "get": { "operationId": "getAmazonSeller", "summary": "Get Seller", "description": "Seller profile, ratings and feedback summary.", "tags": [ "Amazon Sellers" ], "parameters": [ { "name": "seller_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Amazon seller ID (the value of the seller= URL parameter)." }, { "name": "domain", "in": "query", "schema": { "type": "string", "default": "com" }, "description": "Amazon marketplace TLD or code (com, co.uk, de, ...)." } ], "responses": { "200": { "description": "Seller profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "seller": { "$ref": "#/components/schemas/Seller" } } }, "example": { "domain": "com", "seller": { "seller_id": "A1B2C3D4E5F6G7", "name": "TechDeals Store", "link": "https://www.amazon.com/sp?seller=A1B2C3D4E5F6G7", "rating": 4.6, "ratings_total": 8421, "ratings_percentage_positive": 94, "feedback": { "lifetime": { "positive": 94, "neutral": 2, "negative": 4, "count": 8421 }, "12mo": { "positive": 95, "neutral": 2, "negative": 3, "count": 2103 }, "90d": { "positive": 96, "neutral": 1, "negative": 3, "count": 540 }, "30d": { "positive": 97, "neutral": 1, "negative": 2, "count": 182 } }, "business_name": "TechDeals LLC", "business_address": "123 Commerce St, Seattle, WA 98101, US", "member_since": "2017" } } } } } } } }, "/v1/amazon/sellers/{seller_id}/products": { "get": { "operationId": "getAmazonSellerProducts", "summary": "Seller Products", "description": "Products listed in a seller's storefront.", "tags": [ "Amazon Sellers" ], "parameters": [ { "name": "seller_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Amazon seller ID whose storefront to list." }, { "name": "domain", "in": "query", "schema": { "type": "string", "default": "com" }, "description": "Amazon marketplace TLD or code (com, co.uk, de, ...)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number for paginated storefront results." } ], "responses": { "200": { "description": "Seller storefront products", "content": { "application/json": { "schema": { "type": "object", "properties": { "seller_id": { "type": "string" }, "domain": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "seller_id": "A1B2C3D4E5F6G7", "domain": "com", "results": [ { "position": 1, "asin": "B0CX23V2ZK", "title": "Anker Prime Power Bank (2026)", "link": "https://www.amazon.com/dp/B0CX23V2ZK", "image": "https://m.media-amazon.com/images/I/61new.jpg", "price": { "value": 129.99, "currency": "USD", "symbol": "$", "raw": "$129.99" }, "list_price": null, "unit_price": null, "rating": 4.6, "ratings_total": 842, "is_prime": true, "is_sponsored": false, "is_amazons_choice": false, "is_best_seller": false, "bought_past_month": null, "coupon": null, "availability": "In Stock" } ], "pagination": { "current_page": 1, "total_pages": 4, "total_results": 96 } } } } } } } }, "/v1/amazon/sellers/{seller_id}/feedback": { "get": { "operationId": "getAmazonSellerFeedback", "summary": "Seller Feedback", "description": "Buyer feedback entries for a seller.", "tags": [ "Amazon Sellers" ], "parameters": [ { "name": "seller_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Amazon seller ID whose feedback to list." }, { "name": "domain", "in": "query", "schema": { "type": "string", "default": "com" }, "description": "Amazon marketplace TLD or code (com, co.uk, de, ...)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number for paginated feedback entries." } ], "responses": { "200": { "description": "Seller feedback entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "seller_id": { "type": "string" }, "domain": { "type": "string" }, "feedback": { "type": "array", "items": { "type": "object", "properties": { "rating": { "type": "integer", "description": "Star rating left by the buyer (1-5)." }, "body": { "type": "string", "description": "Feedback comment text." }, "date_raw": { "type": "string", "description": "Raw date string as shown on Amazon." }, "date_at": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp of the feedback." }, "rater": { "type": "string", "nullable": true, "description": "Buyer display name, if shown." } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "seller_id": "A1B2C3D4E5F6G7", "domain": "com", "feedback": [ { "rating": 5, "body": "Fast shipping and item exactly as described. Would buy again.", "date_raw": "Reviewed on May 30, 2026", "date_at": "2026-05-30T00:00:00Z", "rater": "M. K." } ], "pagination": { "current_page": 1, "total_pages": 50, "total_results": 500 } } } } } } } }, "/v1/amazon/markets": { "get": { "operationId": "listAmazonMarkets", "summary": "List Markets", "description": "List all supported Amazon marketplaces.", "tags": [ "Amazon Reference" ], "parameters": [], "responses": { "200": { "description": "Supported marketplaces", "content": { "application/json": { "schema": { "type": "object", "properties": { "markets": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Market code (e.g. US, UK, DE)." }, "domain": { "type": "string", "description": "Amazon domain TLD for this market (e.g. com, co.uk)." }, "name": { "type": "string", "description": "Marketplace country name." }, "currency": { "type": "string", "description": "ISO 4217 currency code." }, "language": { "type": "string", "description": "Default locale for this market." }, "country_code": { "type": "string", "description": "ISO country code used for proxy geo-targeting." } } } } } }, "example": { "markets": [ { "code": "US", "domain": "com", "name": "United States", "currency": "USD", "language": "en-US", "country_code": "US" }, { "code": "UK", "domain": "co.uk", "name": "United Kingdom", "currency": "GBP", "language": "en-GB", "country_code": "GB" }, { "code": "DE", "domain": "de", "name": "Germany", "currency": "EUR", "language": "de-DE", "country_code": "DE" }, { "code": "JP", "domain": "co.jp", "name": "Japan", "currency": "JPY", "language": "ja-JP", "country_code": "JP" } ] } } } } } } }, "/v1/amazon/categories": { "get": { "operationId": "listAmazonCategories", "summary": "List Categories", "description": "List common Amazon department/category aliases and bestseller nodes.", "tags": [ "Amazon Reference" ], "parameters": [ { "name": "domain", "in": "query", "schema": { "type": "string", "default": "com" }, "description": "Amazon marketplace TLD or code. Category aliases are scoped per marketplace." } ], "responses": { "200": { "description": "Category aliases", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "alias": { "type": "string", "description": "Category alias usable in the search category parameter (the i= value)." }, "name": { "type": "string", "description": "Human-readable department name." }, "bestsellers_node": { "type": "string", "nullable": true, "description": "Browse-node slug usable with bestsellers / new-releases." } } } } } }, "example": { "domain": "com", "categories": [ { "alias": "electronics", "name": "Electronics", "bestsellers_node": "electronics" }, { "alias": "stripbooks", "name": "Books", "bestsellers_node": "books" }, { "alias": "fashion", "name": "Clothing, Shoes & Jewelry", "bestsellers_node": "fashion" }, { "alias": "toys-and-games", "name": "Toys & Games", "bestsellers_node": "toys-and-games" } ] } } } } } } } }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "AmazonPrice": { "type": "object", "properties": { "value": { "type": "number", "nullable": true, "description": "Numeric price value." }, "currency": { "type": "string", "nullable": true, "description": "ISO 4217 currency code." }, "symbol": { "type": "string", "nullable": true, "description": "Currency symbol (e.g. $, £, €)." }, "raw": { "type": "string", "nullable": true, "description": "Price exactly as displayed on Amazon." } } }, "Pagination": { "type": "object", "properties": { "current_page": { "type": "integer", "description": "Current page number." }, "total_pages": { "type": "integer", "description": "Total number of pages available." }, "total_results": { "type": "integer", "description": "Total number of results across all pages." } } }, "SearchResult": { "type": "object", "properties": { "position": { "type": "integer", "description": "Position of the result on the page (1-based)." }, "asin": { "type": "string", "description": "Amazon Standard Identification Number." }, "title": { "type": "string", "description": "Product title." }, "link": { "type": "string", "description": "Full URL to the product page." }, "image": { "type": "string", "description": "Primary product image URL." }, "price": { "$ref": "#/components/schemas/AmazonPrice" }, "list_price": { "$ref": "#/components/schemas/AmazonPrice" }, "unit_price": { "type": "string", "nullable": true, "description": "Unit price string (e.g. \"$0.50 / count\")." }, "rating": { "type": "number", "nullable": true, "description": "Average star rating (0-5)." }, "ratings_total": { "type": "integer", "nullable": true, "description": "Total number of ratings." }, "is_prime": { "type": "boolean", "description": "Whether the item is Prime-eligible." }, "is_sponsored": { "type": "boolean", "description": "Whether the result is a sponsored placement." }, "is_amazons_choice": { "type": "boolean", "description": "Whether the item has the Amazon's Choice badge." }, "is_best_seller": { "type": "boolean", "description": "Whether the item has the Best Seller badge." }, "bought_past_month": { "type": "string", "nullable": true, "description": "Purchase-volume hint (e.g. \"5K+ bought in past month\")." }, "coupon": { "type": "string", "nullable": true, "description": "Coupon text, if any." }, "availability": { "type": "string", "nullable": true, "description": "Availability/stock message." } } }, "Product": { "type": "object", "properties": { "asin": { "type": "string" }, "parent_asin": { "type": "string", "nullable": true }, "title": { "type": "string" }, "link": { "type": "string" }, "brand": { "type": "string", "nullable": true }, "manufacturer": { "type": "string", "nullable": true }, "model_number": { "type": "string", "nullable": true }, "price": { "$ref": "#/components/schemas/AmazonPrice" }, "list_price": { "$ref": "#/components/schemas/AmazonPrice" }, "savings_amount": { "$ref": "#/components/schemas/AmazonPrice" }, "discount_percent": { "type": "integer", "nullable": true }, "rating": { "type": "number", "nullable": true }, "ratings_total": { "type": "integer", "nullable": true }, "rating_breakdown": { "type": "object", "description": "Percentage of ratings per star bucket (five_star ... one_star)." }, "bought_past_month": { "type": "string", "nullable": true }, "in_stock": { "type": "boolean" }, "availability": { "type": "string", "nullable": true }, "feature_bullets": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string", "nullable": true }, "main_image": { "type": "string", "nullable": true }, "images": { "type": "array", "items": { "type": "string" } }, "images_count": { "type": "integer" }, "videos": { "type": "array", "items": { "type": "string" } }, "videos_count": { "type": "integer" }, "has_aplus_content": { "type": "boolean" }, "variants": { "type": "array", "items": { "type": "object" }, "description": "Variation children with asin, attributes, price, is_current." }, "variant_asins": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "object" }, "description": "Breadcrumb categories." }, "bestsellers_rank": { "type": "array", "items": { "type": "object" }, "description": "Best-seller ranks with rank, category, link." }, "attributes": { "type": "object" }, "specifications": { "type": "object" }, "dimensions": { "type": "string", "nullable": true }, "weight": { "type": "string", "nullable": true }, "first_available": { "type": "string", "nullable": true }, "country_of_origin": { "type": "string", "nullable": true }, "buybox": { "type": "object", "description": "Buy Box winner: seller_name, seller_id, price, fulfillment." }, "sold_by": { "type": "string", "nullable": true }, "ships_from": { "type": "string", "nullable": true }, "fulfilled_by": { "type": "string", "nullable": true }, "is_amazon_seller": { "type": "boolean" }, "badges": { "type": "object", "description": "amazons_choice, amazons_choice_keyword, best_seller, prime, climate_pledge_friendly." }, "coupon": { "type": "object", "nullable": true }, "deal": { "type": "object", "nullable": true }, "delivery": { "type": "object", "nullable": true }, "frequently_bought_together": { "type": "array", "items": { "type": "string" } }, "also_bought": { "type": "array", "items": { "type": "string" } }, "answered_questions": { "type": "integer", "nullable": true }, "top_reviews": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } }, "scraped_utc": { "type": "number" }, "scraped_at": { "type": "string" } } }, "Offer": { "type": "object", "properties": { "position": { "type": "integer" }, "seller": { "type": "object", "description": "Seller summary: name, id, link, rating, ratings_total, ratings_percentage_positive." }, "price": { "$ref": "#/components/schemas/AmazonPrice" }, "condition": { "type": "object", "description": "is_new, title, comments." }, "delivery": { "type": "object", "description": "is_free, fulfilled_by_amazon, date, price." }, "buybox_winner": { "type": "boolean", "description": "Whether this offer currently wins the Buy Box." }, "is_prime": { "type": "boolean" }, "minimum_order_quantity": { "type": "integer", "nullable": true }, "maximum_order_quantity": { "type": "integer", "nullable": true } } }, "Review": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "rating": { "type": "integer", "description": "Star rating left by the reviewer (1-5)." }, "date_raw": { "type": "string", "nullable": true }, "date_utc": { "type": "number", "nullable": true }, "date_at": { "type": "string", "nullable": true }, "review_country": { "type": "string", "nullable": true }, "is_global_review": { "type": "boolean" }, "profile": { "type": "object", "description": "Reviewer profile: name, link, id, image." }, "verified_purchase": { "type": "boolean" }, "vine_program": { "type": "boolean" }, "helpful_votes": { "type": "integer", "nullable": true }, "variant": { "type": "string", "nullable": true }, "images": { "type": "array", "items": { "type": "string" } } } }, "Bestseller": { "type": "object", "properties": { "rank": { "type": "integer", "description": "Best-seller / new-release rank." }, "position": { "type": "integer", "description": "Position on the page." }, "asin": { "type": "string" }, "title": { "type": "string" }, "link": { "type": "string" }, "image": { "type": "string" }, "rating": { "type": "number", "nullable": true }, "ratings_total": { "type": "integer", "nullable": true }, "price": { "$ref": "#/components/schemas/AmazonPrice" } } }, "Deal": { "type": "object", "properties": { "position": { "type": "integer" }, "asin": { "type": "string" }, "title": { "type": "string" }, "link": { "type": "string" }, "image": { "type": "string" }, "deal_price": { "$ref": "#/components/schemas/AmazonPrice" }, "list_price": { "$ref": "#/components/schemas/AmazonPrice" }, "discount_percent": { "type": "integer", "nullable": true }, "deal_type": { "type": "string", "nullable": true }, "is_lightning_deal": { "type": "boolean" }, "badge": { "type": "string", "nullable": true }, "ends_at_utc": { "type": "number", "nullable": true }, "ends_at": { "type": "string", "nullable": true } } }, "Seller": { "type": "object", "properties": { "seller_id": { "type": "string" }, "name": { "type": "string" }, "link": { "type": "string" }, "rating": { "type": "number", "nullable": true }, "ratings_total": { "type": "integer", "nullable": true }, "ratings_percentage_positive": { "type": "integer", "nullable": true }, "feedback": { "type": "object", "description": "Feedback windows (lifetime, 12mo, 90d, 30d) each with positive, neutral, negative, count." }, "business_name": { "type": "string", "nullable": true }, "business_address": { "type": "string", "nullable": true }, "member_since": { "type": "string", "nullable": true } } } } } }