{ "openapi": "3.1.0", "info": { "title": "Apiguru Amazon Data API", "version": "1.1.22", "summary": "Real-time structured Amazon marketplace data: product details, reviews, search, best-sellers, deals, seller profiles, and live offers/stock across 20 country marketplaces.", "description": "Real-time structured Amazon marketplace data: product details, reviews, search, best-sellers, deals, seller profiles, and live offers/stock across 20 country marketplaces.\n\n## Two ways to call this API\n\n**Humans / existing customers** — send `X-API-KEY` against `https://dash.apiguru.app/api/v1`.\n\n**AI agents** — call `https://agent.apiguru.app/agent/v1` with no credentials at all. You get 3 free calls per 24h, then an HTTP 402 with a `PAYMENT-REQUIRED` challenge you settle in USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) on Base mainnet (eip155:8453). No account, no API key, no subscription.\n\nAn MCP server is available at `https://mcp.apiguru.app/mcp`.\n\n## Retry policy\n\nRetry 429, 500, 502, 503, 504 and client-side timeouts with backoff -- none of them are billed. Never retry 400, 401, 403, 404 or 413: the request itself is the problem and repeating it will not change the answer.\n", "contact": { "email": "support@apiguru.app" } }, "servers": [ { "url": "https://dash.apiguru.app/api/v1", "description": "Keyed API (X-API-KEY)" }, { "url": "https://agent.apiguru.app/agent/v1", "description": "Keyless agent gateway (x402, USDC on Base)" } ], "security": [ { "ApiKeyHeader": [] }, { "ApiKeyQuery": [] }, {} ], "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-KEY" }, "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key" } }, "schemas": { "Error": { "type": "object", "description": "Every field an agent needs to decide what to do next is in the body, not only in headers -- many agent HTTP clients show the model the body and hide the status line and headers entirely.", "properties": { "error": { "type": "string", "description": "Human-readable cause." }, "code": { "type": "string", "description": "Stable machine-readable cause; branch on this.", "enum": [ "missing_parameter", "invalid_parameter", "too_many_items", "payment_required", "unknown_endpoint", "upstream_unavailable", "rate_limited", "upstream_rejected" ] }, "param": { "type": "string", "description": "The offending parameter, when there is one." }, "http_status": { "type": "integer" }, "billed": { "type": "boolean", "description": "Whether this answer cost you anything." }, "retryable": { "type": "boolean", "description": "Whether repeating the identical request can succeed." }, "next_step": { "type": "string", "description": "What to do about it, in words." }, "free_calls_remaining": { "type": "integer" }, "price_next_call": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "error" ] } } }, "paths": { "/v2/product-details": { "get": { "operationId": "product_details", "summary": "Full product detail for a single ASIN", "description": "Fetches the complete product record for one ASIN on one marketplace: title, price, star rating, rating count, images, description, feature bullets, variations and category.\n\n**Price:** $0.01 per call\n\n**Notes:** 404 means the ASIN is absent from that marketplace and IS billed. 503 means our fetch failed and is NOT billed - retry. Bullet points and specs are what Amazon shows for the listing; on multi-variant listings they can describe the product family rather than the exact variant. A null field means Amazon did not show it.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "asin", "in": "query", "required": true, "description": "Single Amazon ASIN, 10 uppercase alphanumeric characters. Exactly one - comma-separated lists are rejected; use product_details_batch for many.", "schema": { "type": "string", "pattern": "^[A-Z0-9]{10}$" } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "asin": "B09DJLW458", "product_title": "Example Product", "product_price": "$29.99", "product_star_rating": "4.5", "product_num_ratings": 1284 }, "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway -- our reverse proxy could not get an answer from the gateway. NOT billed. Same class as 503: retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout. The upstream fetch ran past its deadline. NOT billed. Retry with backoff; a narrower query often succeeds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "timeout": { "description": "No response before your own client's deadline. Nothing is billed for a request we never answered. Cold-geo sessions are the slow case and are bounded at 25s server-side; allow 60s.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/product_details_bp.py" } }, "/v2/product-reviews": { "get": { "operationId": "product_reviews", "summary": "Customer reviews for a single ASIN", "description": "Returns the review block for one ASIN: overall star rating, total rating count, Amazon's 'customers say' AI summary, and the individual review list.\n\n**Price:** $0.01 per call\n\n**Notes:** Same 404-billed / 503-not-billed semantics as product_details. Takes no filters: it returns the rating, rating count, the 'customers say' summary and the reviews Amazon shows on the product page itself. There is no paging, star filter or sort -- Amazon's review pages require a signed-in customer, and the API does not sign in. For per-star counts read the rating histogram on product_details.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "asin", "in": "query", "required": true, "description": "Single Amazon ASIN, 10 uppercase alphanumeric characters.", "schema": { "type": "string", "pattern": "^[A-Z0-9]{10}$" } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "asin": "B09DJLW458", "product_title": "Example Product", "product_star_rating": "4.5", "product_num_ratings": 1284, "customers_say": "Customers like the build quality and value.", "product_reviews": [] }, "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway -- our reverse proxy could not get an answer from the gateway. NOT billed. Same class as 503: retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout. The upstream fetch ran past its deadline. NOT billed. Retry with backoff; a narrower query often succeeds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "timeout": { "description": "No response before your own client's deadline. Nothing is billed for a request we never answered. Cold-geo sessions are the slow case and are bounded at 25s server-side; allow 60s.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/product_reviews_v2_bp.py" } }, "/search": { "get": { "operationId": "search", "summary": "Search Amazon products by keyword", "description": "Search Amazon products by keyword. Filters: page, sort_by, category_id (browse node), min_price / max_price (decimals), product_condition (NEW / USED / RENEWED), brand, seller_id, today_deals and deal_type (coupons, all_discounts, buy_more_save_more). Every answer carries filters_applied, filters_ignored (with the reason) and available_filters for that marketplace.\n\n**Price:** $0.01 per call\n\n**Notes:** Blank values and the literal string 'null' are treated as unset. Invalid page, sort_by, price, product_condition or deal_type is a free 400 naming the parameter and the allowed values. Condition and deal refinements use per-marketplace node ids captured from Amazon's own search pages; a marketplace that lacks one gets the unfiltered feed plus an entry under filters_ignored, never a silent empty page. `product_num_ratings` and `offers_count` are integers; `product_star_rating`, `product_price` and `product_original_price` are decimal strings; a null field means Amazon did not show it. `is_prime` is true when the result carries a Prime badge or its delivery line offers Prime delivery. `metadata.total_pages` says how far `page` can go. A full page is up to 48 results and about 54 KB; the tool returns the first 10 as light rows by default and the answer carries `_truncated`, `_omitted_fields`, `_projection` and `_notes`.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search keywords. Required and must be non-empty.", "schema": { "type": "string", "minLength": 1 } }, { "name": "page", "in": "query", "required": false, "description": "Result page, 1-based. metadata.total_pages says how far it goes.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Result ordering.", "schema": { "type": "string", "enum": [ "RELEVANCE", "BEST_SELLERS", "LOW_HIGH_PRICE", "HIGH_LOW_PRICE", "REVIEWS", "NEWEST" ], "default": "RELEVANCE" } }, { "name": "category_id", "in": "query", "required": false, "description": "Amazon browse node id to restrict to, e.g. 172282 (Electronics on US). Take one from a best_sellers answer's available_subcategories, a product's category_path, or node= in an Amazon URL. Ids differ per marketplace.", "schema": { "type": "string" } }, { "name": "min_price", "in": "query", "required": false, "description": "Lowest price, in the marketplace currency; decimals such as 19.99 are fine.", "schema": { "type": "number", "minimum": 0 } }, { "name": "max_price", "in": "query", "required": false, "description": "Highest price, in the marketplace currency.", "schema": { "type": "number", "minimum": 0 } }, { "name": "product_condition", "in": "query", "required": false, "description": "NEW, USED or RENEWED (case-insensitive). Applied with the marketplace's own condition node; where a marketplace does not offer one, the answer's filters_ignored says so and available_filters lists what it does offer.", "schema": { "type": "string", "enum": [ "NEW", "USED", "RENEWED" ] } }, { "name": "brand", "in": "query", "required": false, "description": "Brand name as Amazon spells it (case-insensitive), e.g. Samsung.", "schema": { "type": "string" } }, { "name": "seller_id", "in": "query", "required": false, "description": "Restrict results to one seller's offers (Amazon seller id).", "schema": { "type": "string" } }, { "name": "today_deals", "in": "query", "required": false, "description": "Only items in Today's Deals, using that marketplace's own refinement. Where a marketplace has none (amazon.fr on 2026-09-08) it is reported under filters_ignored.", "schema": { "type": "boolean", "default": false } }, { "name": "deal_type", "in": "query", "required": false, "description": "A specific promotion refinement: today_deals, all_discounts, coupons or buy_more_save_more. available_filters.deal_type lists the ones this marketplace has.", "schema": { "type": "string", "enum": [ "today_deals", "all_discounts", "coupons", "buy_more_save_more" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "metadata": { "page_number": 1, "total": 1283, "page_size": 48, "total_pages": 27 }, "filters_applied": { "min_price": 19.99, "max_price": 30.0, "product_condition": "NEW" }, "filters_ignored": [], "available_filters": { "product_condition": [ "NEW", "USED", "RENEWED" ], "deal_type": [ "today_deals", "all_discounts", "coupons", "buy_more_save_more" ], "sort_by": [ "RELEVANCE", "BEST_SELLERS", "LOW_HIGH_PRICE", "HIGH_LOW_PRICE", "REVIEWS", "NEWEST" ] }, "products": [ { "asin": "B0888TJNH1", "product_title": "Womens Capri V Sporty Flip Flop", "product_price": "24.95", "product_star_rating": "4.5", "product_num_ratings": 5167, "badges": [], "delivery": { "free_delivery_date": "Thu, Sep 10" } } ], "amazon_request_count": 1, "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway -- our reverse proxy could not get an answer from the gateway. NOT billed. Same class as 503: retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout. The upstream fetch ran past its deadline. NOT billed. Retry with backoff; a narrower query often succeeds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "timeout": { "description": "No response before your own client's deadline. Nothing is billed for a request we never answered. Cold-geo sessions are the slow case and are bounded at 25s server-side; allow 60s.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/search_product_bp.py" } }, "/product": { "get": { "operationId": "product_details_batch", "summary": "Product detail for up to 20 ASINs in one call", "description": "Batch variant of product_details. Accepts a comma-separated ASIN list, deduplicates it, and fetches all of them concurrently. Far cheaper and faster than N single calls.\n\n**Price:** $0.008 per item (max 20)\n\n**Notes:** Billed per ASIN processed, including ones that come back not-found. More than 20 ASINs returns 413. Bullet points and specs are what Amazon shows for the listing; on multi-variant listings they can describe the product family rather than the exact variant. A null field means Amazon did not show it.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "asins", "in": "query", "required": true, "description": "Comma-separated ASIN list, maximum 20 after de-duplication. Each must be 10 uppercase alphanumeric characters.", "schema": { "type": "string", "pattern": "^[A-Z0-9]{10}(,[A-Z0-9]{10})*$" } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [ { "asin": "B09DJLW458", "product_title": "Example Product" } ], "billable_requests_count": 1, "amazon_request_count": 1, "response_time": "1420ms", "country_code": "US", "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway -- our reverse proxy could not get an answer from the gateway. NOT billed. Same class as 503: retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout. The upstream fetch ran past its deadline. NOT billed. Retry with backoff; a narrower query often succeeds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "timeout": { "description": "No response before your own client's deadline. Nothing is billed for a request we never answered. Cold-geo sessions are the slow case and are bounded at 25s server-side; allow 60s.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "per_item", "unitPriceUsd": "0.008", "countParam": "asins", "countSeparator": ",", "maxItems": 20, "countDedup": true }, "x-apiguru-source": "blueprints/product_details_batch_bp.py" } }, "/stock": { "get": { "operationId": "offers_stock", "summary": "Live offers and inventory for up to 10 ASINs", "description": "Returns the current offer list per ASIN (seller, price, condition, buy-box winner) and, optionally, the actual purchasable stock quantity.\n\n**Price:** $0.015 per item (max 10)\n\n**Notes:** Billed per upstream Amazon request, which is more than one per ASIN when check_inventory is true. /scrape is a legacy alias for the same handler.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "asins", "in": "query", "required": true, "description": "Comma-separated ASIN list, maximum 10. Each must be 10 uppercase alphanumeric characters; malformed entries are rejected with 400.", "schema": { "type": "string", "pattern": "^[A-Z0-9]{10}(,[A-Z0-9]{10})*$" } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } }, { "name": "check_inventory", "in": "query", "required": false, "description": "Resolve the true purchasable stock quantity. Slower and bills more upstream requests, so leave off unless you need the number.", "schema": { "type": "boolean", "default": false } }, { "name": "offers_count", "in": "query", "required": false, "description": "'all' for every offer, 'winner' for the buy-box offer only, or a specific alphanumeric Offer ID.", "schema": { "type": "string", "default": "all" } }, { "name": "condition", "in": "query", "required": false, "description": "Comma-separated condition filter: ALL, NEW, USED_LIKE_NEW, USED_VERY_GOOD, USED_GOOD, USED_ACCEPTABLE (case-insensitive). Omit for every offer. An unknown value is a free 400 listing the allowed ones; it used to be silently treated as ALL.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [ { "asin": "B09DJLW458", "offers": [], "stock": 42 } ], "amazon_request_count": 1, "response_time": 2100, "country_code": "US", "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway -- our reverse proxy could not get an answer from the gateway. NOT billed. Same class as 503: retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout. The upstream fetch ran past its deadline. NOT billed. Retry with backoff; a narrower query often succeeds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "timeout": { "description": "No response before your own client's deadline. Nothing is billed for a request we never answered. Cold-geo sessions are the slow case and are bounded at 25s server-side; allow 60s.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "per_item", "unitPriceUsd": "0.015", "countParam": "asins", "countSeparator": ",", "maxItems": 10, "countDedup": false }, "x-apiguru-source": "blueprints/offers_stock_bp.py" } }, "/scrape": { "get": { "operationId": "offers_stock_alias", "summary": "Live offers and inventory for up to 10 ASINs (legacy alias of /stock)", "description": "Returns the current offer list per ASIN (seller, price, condition, buy-box winner) and, optionally, the actual purchasable stock quantity.\n\n**Price:** $0.015 per item (max 10)\n\n**Notes:** Billed per upstream Amazon request, which is more than one per ASIN when check_inventory is true. /scrape is a legacy alias for the same handler.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "asins", "in": "query", "required": true, "description": "Comma-separated ASIN list, maximum 10. Each must be 10 uppercase alphanumeric characters; malformed entries are rejected with 400.", "schema": { "type": "string", "pattern": "^[A-Z0-9]{10}(,[A-Z0-9]{10})*$" } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } }, { "name": "check_inventory", "in": "query", "required": false, "description": "Resolve the true purchasable stock quantity. Slower and bills more upstream requests, so leave off unless you need the number.", "schema": { "type": "boolean", "default": false } }, { "name": "offers_count", "in": "query", "required": false, "description": "'all' for every offer, 'winner' for the buy-box offer only, or a specific alphanumeric Offer ID.", "schema": { "type": "string", "default": "all" } }, { "name": "condition", "in": "query", "required": false, "description": "Comma-separated condition filter: ALL, NEW, USED_LIKE_NEW, USED_VERY_GOOD, USED_GOOD, USED_ACCEPTABLE (case-insensitive). Omit for every offer. An unknown value is a free 400 listing the allowed ones; it used to be silently treated as ALL.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [ { "asin": "B09DJLW458", "offers": [], "stock": 42 } ], "amazon_request_count": 1, "response_time": 2100, "country_code": "US", "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway -- our reverse proxy could not get an answer from the gateway. NOT billed. Same class as 503: retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout. The upstream fetch ran past its deadline. NOT billed. Retry with backoff; a narrower query often succeeds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "timeout": { "description": "No response before your own client's deadline. Nothing is billed for a request we never answered. Cold-geo sessions are the slow case and are bounded at 25s server-side; allow 60s.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "per_item", "unitPriceUsd": "0.015", "countParam": "asins", "countSeparator": ",", "maxItems": 10, "countDedup": false }, "x-apiguru-source": "blueprints/offers_stock_bp.py", "deprecated": true } }, "/v2/best-sellers": { "get": { "operationId": "best_sellers", "summary": "Best-seller rankings for a category", "description": "Best-seller rankings for a department of one marketplace, 50 per page. Every answer carries the department it resolved to, available_categories (that marketplace's departments with slugs) and available_subcategories (the children of the department shown, with the ids subcategory_code takes).\n\n**Price:** $0.01 per call\n\n**Notes:** No required parameters - calling it bare returns US appliances page 1. `category` accepts a slug, a display name, or one of the older US department names; page is capped at 5 (a 400 beyond, not a 500). `rank` is the position within the requested list on this page. Rows are the same for every marketplace; only the department vocabulary differs, and the answer carries it.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Best-seller department, by slug or by name as Amazon shows it for that marketplace (case-insensitive; a unique fragment works). Departments and their slugs differ per marketplace: amazon.com has electronics, amazon.de has ce-de (Electronics & Photo). Every answer lists that marketplace's departments under available_categories; an unknown or ambiguous name is a free 400 listing them.", "schema": { "type": "string", "default": "appliances" } }, { "name": "subcategory_code", "in": "query", "required": false, "description": "Browse node id of a child of `category`, from available_subcategories of a previous answer for that category (a name from that list works too).", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Result page, 1-based, 50 rows each; Amazon's lists stop at page 5.", "schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 1 } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "category": { "slug": "electronics", "name": "Electronics", "subcategory_code": null, "subcategory_name": null }, "page": 1, "page_size": 50, "max_page": 5, "available_categories": [ { "slug": "electronics", "name": "Electronics" }, { "slug": "pc", "name": "Computers & Accessories" } ], "available_subcategories": [ { "id": "502394", "name": "Camera & Photo" }, { "id": "541966", "name": "Computers & Accessories" } ], "data": [ { "rank": "1", "asin": "B08JHCVHTY", "title": "Blink Plus Plan", "price": "$11.99", "star_rating": "4.4", "num_ratings": "279,960", "url": "https://www.amazon.com/dp/B08JHCVHTY", "photo_url": "https://m.media-amazon.com/images/I/41abc.jpg" } ], "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway -- our reverse proxy could not get an answer from the gateway. NOT billed. Same class as 503: retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout. The upstream fetch ran past its deadline. NOT billed. Retry with backoff; a narrower query often succeeds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "timeout": { "description": "No response before your own client's deadline. Nothing is billed for a request we never answered. Cold-geo sessions are the slow case and are bounded at 25s server-side; allow 60s.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/best_sellers_bp.py" } }, "/v2/deals": { "get": { "operationId": "deals", "summary": "Current Amazon deals with filters", "description": "Returns the current Amazon deals feed: ASIN, title, deal price, list price, discount, deal badge, start/end time and product links. Filter by department (categories), brand id (brands), rating cut-off, price bounds, minimum discount and Prime program. Every answer carries available_filters (the category and brand ids this marketplace accepts, with names), filters_applied / filters_ignored (what took effect) and next_offset (the next page, null when the feed ends).\n\n**Price:** $0.01 per call\n\n**Notes:** Filters are by id: categories takes a department id or name, brands takes brand ids only; available_filters in every answer lists both with names, and filters_applied / filters_ignored report what Amazon honoured. A page is 30 rows; page with offset=next_offset (null when exhausted); total_count caps at 500. min_price, max_price, min_discount and max_discount are applied to the rows after the fetch, scanning up to 3 upstream pages per call, so a page can hold fewer than 30 rows and total_count does not reflect them. An empty answer carries a hint saying why. Deal prices expire: check deal_ends_at. The older price_range and discount_range parameters are still accepted, as buckets (1-5 = under 25 / 25-50 / 50-100 / 100-200 / 200 and up; 1-4 = 10 / 25 / 50 / 70 percent off or more) or as bands such as 25-50 and 70+.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } }, { "name": "offset", "in": "query", "required": false, "description": "Row to start at. A page is 30 rows; pass the previous answer's next_offset for the next page.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "categories", "in": "query", "required": false, "description": "Department to restrict to: its id from available_filters.categories, or its name as Amazon shows it for that marketplace (case-insensitive; a unique fragment such as \"electronics\" works). US departments: Amazon Devices & Accessories, Appliances, Arts Crafts & Sewing, Audible Books & Originals, Automotive, Baby Products, Beauty & Personal Care, Books, CDs & Vinyl, Cell Phones & Accessories, Clothing Shoes & Jewelry, Collectibles & Fine Art, Electronics, Everything Else, Grocery & Gourmet Food, Handmade Products, Health & Household, Home & Kitchen, Industrial & Scientific, Kindle Store, Movies & TV, Musical Instruments, Office Products, Patio Lawn & Garden, Pet Supplies, Software, Sports & Outdoors, Tools & Home Improvement, Toys & Games, Video Games. Other marketplaces use their own localised names -- read them from available_filters.categories of any deals answer for that geo. An unknown name is a free 400 listing the valid names.", "schema": { "type": "string" } }, { "name": "brands", "in": "query", "required": false, "description": "Comma-separated brand ids, e.g. 46655 for Samsung on US. Take them from brand_id on any deals row or from available_filters.brands (the brands present in the current result). Names resolve only when this marketplace has already shown that brand; for a brand by name use /search with brand= and today_deals=true instead.", "schema": { "type": "string" } }, { "name": "min_product_star_rating", "in": "query", "required": false, "description": "Amazon's deals feed offers one rating cut-off: 4 = four stars and up. ALL or omitted = no cut-off. Other values are rejected with a free 400.", "schema": { "type": "string", "enum": [ "4", "ALL" ] } }, { "name": "min_price", "in": "query", "required": false, "description": "Lowest deal price to return, in the marketplace currency. Applied to the fetched rows; see notes.", "schema": { "type": "number", "minimum": 0 } }, { "name": "max_price", "in": "query", "required": false, "description": "Highest deal price to return, in the marketplace currency.", "schema": { "type": "number", "minimum": 0 } }, { "name": "min_discount", "in": "query", "required": false, "description": "Smallest discount percentage to return, e.g. 50 for half price or better.", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "max_discount", "in": "query", "required": false, "description": "Largest discount percentage to return.", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "prime_exclusive", "in": "query", "required": false, "description": "Only deals in Amazon's Prime Exclusive program.", "schema": { "type": "boolean", "default": false } }, { "name": "prime_early_access", "in": "query", "required": false, "description": "Only Prime Early Access deals. A marketplace lists the programs it is running under available_filters.prime_programs; when Early Access is not running the answer is empty with a hint saying so.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "deals": { "total_count": 500, "page_size": 30, "next_offset": 30, "filters_applied": { "categories": [ { "id": "493964", "name": "Electronics" } ], "min_discount": 30 }, "filters_ignored": [], "available_filters": { "categories": [ { "id": "493964", "name": "Electronics" } ], "brands": [ { "id": "46655", "name": "Samsung" } ], "min_product_star_rating": [ "4" ], "price": { "min": 0, "max": 5900, "currency": "USD" }, "discount_percent": { "min": 0, "max": 100 }, "prime_programs": [ { "id": "1", "name": "Prime Exclusive", "param": "prime_exclusive" } ] }, "data": [ { "asin": "B0H12RV546", "deal_title": "Samsung 65-Inch QLED 4K Smart TV", "list_price": "1299.99", "deal_price": "797.99", "currency": "USD", "discount_percentage": "39%", "deal_badge": "39% off", "deal_ends_at": "2026-09-30T06:59:59.000Z", "product_url": "https://www.amazon.com/dp/B0H12RV546", "brand_id": "46655", "department_ids": [ "493964" ] } ] }, "amazon_request_count": 1, "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway -- our reverse proxy could not get an answer from the gateway. NOT billed. Same class as 503: retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout. The upstream fetch ran past its deadline. NOT billed. Retry with backoff; a narrower query often succeeds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "timeout": { "description": "No response before your own client's deadline. Nothing is billed for a request we never answered. Cold-geo sessions are the slow case and are bounded at 25s server-side; allow 60s.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/deals_bp.py" } }, "/seller-profile": { "get": { "operationId": "seller_profile_batch", "summary": "Seller profiles for up to 10 seller IDs", "description": "Returns the storefront profile for each seller id: business name, rating, feedback counts, address and marketplace presence.\n\n**Price:** $0.012 per item (max 10)\n\n**Notes:** Seller ID validation is all-or-nothing: one malformed id rejects the entire request with 400.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "seller_ids", "in": "query", "required": true, "description": "Comma-separated seller IDs, maximum 10. Each must be 13-15 alphanumeric characters or the whole call 400s.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{13,15}(,[A-Za-z0-9]{13,15})*$" } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [ { "seller_id": "A1B2C3D4E5F6G", "business_name": "Example Seller" } ], "billable_requests_count": 1, "amazon_request_count": 1, "response_time": 1800, "country_code": "US", "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway -- our reverse proxy could not get an answer from the gateway. NOT billed. Same class as 503: retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout. The upstream fetch ran past its deadline. NOT billed. Retry with backoff; a narrower query often succeeds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "timeout": { "description": "No response before your own client's deadline. Nothing is billed for a request we never answered. Cold-geo sessions are the slow case and are bounded at 25s server-side; allow 60s.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "per_item", "unitPriceUsd": "0.012", "countParam": "seller_ids", "countSeparator": ",", "maxItems": 10, "countDedup": false }, "x-apiguru-source": "blueprints/seller_profile_batch_bp.py" } }, "/v2/seller-products": { "get": { "operationId": "seller_products", "summary": "Products listed by a seller", "description": "Products listed by a seller: a storefront search. Takes the same filters as search -- query, page, sort_by, category_id, min_price / max_price, product_condition, brand, today_deals, deal_type -- and answers with filters_applied, filters_ignored and available_filters like search does.\n\n**Price:** $0.01 per call\n\n**Notes:** Unlike seller_profile_batch, seller_id format is not pattern-validated here. metadata.total_pages says how far page goes (48 rows a page). Invalid sort_by, price, product_condition or deal_type is a free 400 that lists the allowed values.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "seller_id", "in": "query", "required": true, "description": "Restrict results to one seller's offers (Amazon seller id).", "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": false, "description": "Optional keywords to search within this seller's storefront.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Result page, 1-based. metadata.total_pages says how far it goes.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Result ordering.", "schema": { "type": "string", "enum": [ "RELEVANCE", "BEST_SELLERS", "LOW_HIGH_PRICE", "HIGH_LOW_PRICE", "REVIEWS", "NEWEST" ], "default": "RELEVANCE" } }, { "name": "category_id", "in": "query", "required": false, "description": "Amazon browse node id to restrict to, e.g. 172282 (Electronics on US). Take one from a best_sellers answer's available_subcategories, a product's category_path, or node= in an Amazon URL. Ids differ per marketplace.", "schema": { "type": "string" } }, { "name": "min_price", "in": "query", "required": false, "description": "Lowest price, in the marketplace currency; decimals such as 19.99 are fine.", "schema": { "type": "number", "minimum": 0 } }, { "name": "max_price", "in": "query", "required": false, "description": "Highest price, in the marketplace currency.", "schema": { "type": "number", "minimum": 0 } }, { "name": "product_condition", "in": "query", "required": false, "description": "NEW, USED or RENEWED (case-insensitive). Applied with the marketplace's own condition node; where a marketplace does not offer one, the answer's filters_ignored says so and available_filters lists what it does offer.", "schema": { "type": "string", "enum": [ "NEW", "USED", "RENEWED" ] } }, { "name": "brand", "in": "query", "required": false, "description": "Brand name as Amazon spells it (case-insensitive), e.g. Samsung.", "schema": { "type": "string" } }, { "name": "today_deals", "in": "query", "required": false, "description": "Only items in Today's Deals, using that marketplace's own refinement. Where a marketplace has none (amazon.fr on 2026-09-08) it is reported under filters_ignored.", "schema": { "type": "boolean", "default": false } }, { "name": "deal_type", "in": "query", "required": false, "description": "A specific promotion refinement: today_deals, all_discounts, coupons or buy_more_save_more. available_filters.deal_type lists the ones this marketplace has.", "schema": { "type": "string", "enum": [ "today_deals", "all_discounts", "coupons", "buy_more_save_more" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "products": [] }, "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway -- our reverse proxy could not get an answer from the gateway. NOT billed. Same class as 503: retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout. The upstream fetch ran past its deadline. NOT billed. Retry with backoff; a narrower query often succeeds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "timeout": { "description": "No response before your own client's deadline. Nothing is billed for a request we never answered. Cold-geo sessions are the slow case and are bounded at 25s server-side; allow 60s.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/seller_products_bp.py" } }, "/v2/seller-reviews": { "get": { "operationId": "seller_reviews", "summary": "Feedback reviews for a seller", "description": "Returns paginated seller feedback, optionally filtered to a star-rating window.\n\n**Price:** $0.01 per call\n\n**Notes:** from_rating and to_rating are optional; omit both for unfiltered feedback. A page holds 5 reviews and the answer carries current_page and has_next_page; Amazon exposes no total, so page until has_next_page is false (up to page 100).", "tags": [ "Amazon Data" ], "parameters": [ { "name": "seller_id", "in": "query", "required": true, "description": "Amazon seller ID. Required.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Result page, 1-based, 5 reviews a page; has_next_page in the answer says whether another exists.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "from_rating", "in": "query", "required": false, "description": "Lowest star rating to include, 1-5.", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "to_rating", "in": "query", "required": false, "description": "Highest star rating to include, 1-5.", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "reviews": [] }, "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway -- our reverse proxy could not get an answer from the gateway. NOT billed. Same class as 503: retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout. The upstream fetch ran past its deadline. NOT billed. Retry with backoff; a narrower query often succeeds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "timeout": { "description": "No response before your own client's deadline. Nothing is billed for a request we never answered. Cold-geo sessions are the slow case and are bounded at 25s server-side; allow 60s.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/seller_reviews_bp.py" } } }, "x-apiguru-geos": { "US": "com", "CA": "ca", "DE": "de", "MX": "com.mx", "UK": "co.uk", "FR": "fr", "IT": "it", "ES": "es", "AU": "com.au", "BR": "com.br", "IN": "in", "JP": "co.jp", "NL": "nl", "AE": "ae", "PL": "pl", "SA": "sa", "SG": "sg", "SE": "se", "TR": "com.tr", "BE": "com.be" }, "x-apiguru-conventions": { "asin_pattern": "^[A-Z0-9]{10}$", "asin_note": "Uppercase only. Lowercase ASINs are rejected with 400 - normalise before calling.", "seller_id_pattern": "^[A-Za-z0-9]{13,15}$", "geo_default": "US", "sample_asin": "B09DJLW458", "error_semantics": { "400": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "401": "Missing or invalid API key on the keyed path.", "402": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "403": "Account disabled, or no active subscription plan.", "404": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "413": "Too many items in a batch request.", "429": "Per-second rate limit exceeded for the plan. Back off and retry.", "500": "Internal error. NOT billed.", "502": "Bad gateway -- our reverse proxy could not get an answer from the gateway. NOT billed. Same class as 503: retry with backoff.", "503": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "504": "Gateway timeout. The upstream fetch ran past its deadline. NOT billed. Retry with backoff; a narrower query often succeeds.", "timeout": "No response before your own client's deadline. Nothing is billed for a request we never answered. Cold-geo sessions are the slow case and are bounded at 25s server-side; allow 60s." }, "retry_policy": "Retry 429, 500, 502, 503, 504 and client-side timeouts with backoff -- none of them are billed. Never retry 400, 401, 403, 404 or 413: the request itself is the problem and repeating it will not change the answer.", "sample_seller_id": "A2A1RNLLUK3HYA" } }