# ASINScope API: full reference for LLMs > REST API for Amazon product lookups by ASIN, UPC or EAN across 13 Amazon marketplaces. This file joins the API > reference and the AI integration guide as plain markdown for AI tools. - OpenAPI spec (canonical contract): https://docs.asinscope.com/openapi.json - API reference (browser): https://docs.asinscope.com/asinscope-api/ - AI integration guide (browser): https://docs.asinscope.com/asinscope-api/ai/ - MCP server (for AI assistants, no code): https://api.asinscope.com/mcp, documented at https://docs.asinscope.com/asinscope-api/mcp/ - API plans: https://asinscope.com/en/asin-to-upc-api # ASINScope API Documentation The ASINScope API lets you retrieve detailed Amazon product data (title, brand, UPC, EAN, MPN, imagery, and more) so you can enrich catalogs, validate listings, or power downstream workflows directly from your applications. **Building with an AI assistant?** Point it at the [OpenAPI spec](https://docs.asinscope.com/openapi.json) and read the [AI integration guide](https://docs.asinscope.com/asinscope-api/ai/) for prompt recipes and the mistakes AI-written code makes with this API. The whole reference is also available as plain text at [/llms-full.txt](https://docs.asinscope.com/llms-full.txt). To let an assistant run lookups for you with no code, connect it to the [MCP server](https://docs.asinscope.com/asinscope-api/mcp/). ## Base URL ``` https://api.asinscope.com ``` ## Authentication - Send your API key in the `x-api-key` header on every request. - The `key` query parameter is also accepted, but a key in the URL ends up in logs and proxies, so prefer the header. - Find your key in the ASINScope API Dashboard after subscribing. **Example** ```bash curl --get 'https://api.asinscope.com/products/lookup' \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "asin=B01NAL48FU,B00NNUMI86" \ --data-urlencode "domain=com" ``` ## Products Lookup **Endpoint** `GET /products/lookup` **What it does** Returns product details for up to 10 identifiers per request. Use one identifier type per call: - `asin` — Amazon ASINs - `upc` — UPC codes - `ean` — EAN codes **Parameters (query)** - `asin` | `upc` | `ean` (string, required): Comma-separated list of 1–10 codes (Enterprise plans allow more per request; the `400` error states your limit). Provide only one of these parameters per request. - `domain` (string, optional): Amazon marketplace domain. Default: `com`. Supported: `com`, `ca`, `de`, `fr`, `it`, `nl`, `es`, `in`, `uk`, `jp`, `au`, `mx`, `pl`. - `key` (string, optional): Your API key, if you don't send it in the `x-api-key` header. - `desc` (string, optional): Set to `1` to include the listing `description` and `bullets` (bullet points) in each item. Default: `0` (these fields are omitted to keep responses lighter). **Sample requests** Lookup by ASIN: ```bash curl --get 'https://api.asinscope.com/products/lookup' \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "asin=B01NAL48FU" \ --data-urlencode "domain=com" ``` Lookup by UPC: ```bash curl --get 'https://api.asinscope.com/products/lookup' \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "upc=631102001550,653485442904" \ --data-urlencode "domain=com" ``` Lookup by EAN: ```bash curl --get 'https://api.asinscope.com/products/lookup' \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "ean=4006381333931" \ --data-urlencode "domain=de" ``` Include the listing description and bullet points: ```bash curl --get 'https://api.asinscope.com/products/lookup' \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "asin=B01NAL48FU" \ --data-urlencode "domain=com" \ --data-urlencode "desc=1" ``` **Response** `200 OK` — JSON payload with product data and token usage info. ```json { "items": [ { "asin": "B088H39PXX", "ean": "0793610399007", "upc": "793610399007", "mpn": "2143", "bsr": 95, "category": "Sports & Outdoors", "brand": "CUKU", "title": "Magnetic Dart Board - 12pcs Magnetic Darts (Red Green Yellow) - Excellent Indoor Game and Party Games - Magnetic Dart Board Toys Gifts for 5 6 7 8 9 10 11 12 Year Old Boy Kids", "productGroup": "Sports", "lowestNewPrice": 22.79, "lowestFormattedPrice": "$22.79", "soldByAmazon": false, "packageDimensions": { "height": 1.77, "width": 13.46, "length": 13.58, "weight": 2.07 }, "upcList": ["793610399007"], "eanList": ["0793610399007"], "totalNew": 2, "smallImage": "https://images-na.ssl-images-amazon.com/images/I/91we94LQPhL.jpg", "mediumImage": "https://images-na.ssl-images-amazon.com/images/I/91we94LQPhL.jpg", "images": [ "https://images-na.ssl-images-amazon.com/images/I/91we94LQPhL.jpg", "https://images-na.ssl-images-amazon.com/images/I/91WKu-Y+P4L.jpg", "https://images-na.ssl-images-amazon.com/images/I/91-9rELjLsL.jpg" ] } ], "dailyTokensLeft": 9998, "bucketSize": 119, "msBeforeNextDailyToken": 82524143, "consumedTokens": 1 } ``` `consumedTokens` is the number of tokens charged for this request and `dailyTokensLeft` is your balance after it. For UPC/EAN lookups, `consumedTokens` can be higher than the number of codes you sent: a barcode that matches several listings is charged one token per listing returned. See [Rate Limits](#rate-limits). When `desc=1` is passed, each item additionally includes the listing copy: ```json { "description": "Full product description text from the Amazon listing...", "bullets": [ "Bullet point 1 from the listing", "Bullet point 2 from the listing" ] } ``` These fields are omitted when `desc` is `0` or not provided. `packageDimensions` is in inches (`height`, `width`, `length`) and pounds (`weight`), and is absent when Amazon has no package data. `lowestNewPrice` is a number in the marketplace currency; `lowestFormattedPrice` is the same price with the currency symbol. **Matching items to your codes.** Don't rely on the order of `items` or on it having exactly one entry per code: a barcode can return several listings, and a code that matches nothing has no usable entry. Match results back by `asin` (ASIN lookups) or by `upcList` / `eanList` (barcode lookups). A code with no matching item, or whose item has no `title`, was not found on that marketplace. It still costs one token. **Errors** Every `4xx` error body carries a stable `code` next to the human-readable text. Branch on `code`, not on the text, which may change. | Status | `code` | Description | |--------|--------|-------------| | `400 Bad Request` | `INVALID_REQUEST` | Missing or malformed parameters (e.g., mixed identifier types, unsupported `domain`, no valid ASIN in the list) | | `400 Bad Request` | `TOO_MANY_CODES` | More codes than your plan allows in one request | | `400 Bad Request` | `MISSING_API_KEY` | No API key was sent | | `401 Unauthorized` | `INVALID_API_KEY` | The API key is not valid | | `403 Forbidden` | `NO_ACTIVE_SUBSCRIPTION` | No active subscription | | `429 Too Many Requests` | `DAILY_LIMIT_REACHED` | Daily allowance used up. See [Rate Limits](#rate-limits) | | `429 Too Many Requests` | `TOKEN_BUCKET_EMPTY` | Short-term bucket is empty. See [Rate Limits](#rate-limits) | | `500 Internal Server Error` | | Unexpected server issue | ```json { "error": "Invalid API key", "code": "INVALID_API_KEY" } ``` ## Account Tokens **Endpoint** `GET /account/tokens` **What it does** Returns your current token usage and limits without consuming any tokens. Use this endpoint to check available capacity before making data requests — especially useful when processing jobs from a queue where you want to avoid losing messages if tokens are exhausted. **Parameters** None besides the API key (`x-api-key` header, or the `key` query parameter). **Sample request** ```bash curl 'https://api.asinscope.com/account/tokens' \ -H "x-api-key: YOUR_API_KEY" ``` **Response** `200 OK` — JSON payload with current token status. ```json { "dailyTokensLeft": 9812, "dailyTokensLimit": 10000, "minutelyTokensLeft": 119, "minutelyBucketCapacity": 120, "tokensPerMinute": 60, "msBeforeNextDailyReset": 82524143 } ``` | Field | Description | |-------|-------------| | `dailyTokensLeft` | Remaining tokens for the current day | | `dailyTokensLimit` | Maximum daily tokens for your subscription | | `minutelyTokensLeft` | Current tokens available in the short-term bucket | | `minutelyBucketCapacity` | Maximum bucket capacity for your subscription | | `tokensPerMinute` | Rate at which the bucket refills (tokens per minute) | | `msBeforeNextDailyReset` | Milliseconds until the daily limit resets | **Errors** | Status | `code` | Description | |--------|--------|-------------| | `400 Bad Request` | `MISSING_API_KEY` | No API key was sent | | `401 Unauthorized` | `INVALID_API_KEY` | The API key is not valid | | `403 Forbidden` | `NO_ACTIVE_SUBSCRIPTION` | No active subscription | ## Rate Limits **Daily tokens** - Basic: 1,000 tokens/day - Pro: 10,000 tokens/day **Short-term capacity (rolling bucket)** - Basic: bucket capacity 60 tokens, refill rate 10 tokens/minute - Pro: bucket capacity 120 tokens, refill rate 60 tokens/minute **How tokens are used** - Every identifier you send costs at least one token, even if it matches nothing. - ASIN lookups cost exactly one token per ASIN. - UPC/EAN lookups cost one token per listing returned. A barcode can be shared by several listings, so a single UPC that matches 56 listings costs 56 tokens. The cost of a request is `max(identifiers sent, listings returned)`. - The per-listing charge is applied after the data is fetched, because the number of matches is only known then. One ambiguous barcode can therefore use a large part of your daily balance in a single request. Check `consumedTokens` in the response to see what a request actually cost. - Daily tokens reset at midnight UTC; the short-term bucket refills continuously at the listed rate. **When a limit is hit** Both limits answer `429 Too Many Requests`. Tell them apart by `code`. Each response also says how long to wait, as `retryAfterSeconds` in the body and as a `Retry-After` header. - **Daily limit** (`DAILY_LIMIT_REACHED`): the daily tokens are used up. Stop until the reset. ```json { "statusCode": 429, "message": "Daily limit reached. Please try again in 312 minutes", "error": "Too Many Requests", "code": "DAILY_LIMIT_REACHED", "retryAfterSeconds": 18720 } ``` - **Short-term bucket** (`TOKEN_BUCKET_EMPTY`): the bucket is empty. Wait `retryAfterSeconds`, then retry. ```json { "error": "Not enough tokens in the bucket. Restore rate: 10 / min", "code": "TOKEN_BUCKET_EMPTY", "retryAfterSeconds": 60 } ``` ## Code Samples ### Python (requests) ```python import requests API_KEY = "YOUR_API_KEY" BASE_URL = "https://api.asinscope.com/products/lookup" def lookup_by_asin(asins, domain="com"): params = { "asin": ",".join(asins), "domain": domain, } response = requests.get(BASE_URL, params=params, headers={"x-api-key": API_KEY}, timeout=30) response.raise_for_status() return response.json() if __name__ == "__main__": try: data = lookup_by_asin(["B01NAL48FU", "B00NNUMI86"]) for item in data.get("items", []): print(item["asin"], item.get("upc"), item.get("ean")) except requests.HTTPError as err: error = err.response.json() if error.get("code") == "TOKEN_BUCKET_EMPTY": print(f"Bucket empty: retry in {error['retryAfterSeconds']} seconds.") elif error.get("code") == "DAILY_LIMIT_REACHED": print("Daily limit reached: stop until 00:00 UTC.") else: print(f"Request failed: {err.response.status_code} {err.response.text}") ``` ### Node.js (axios) ```javascript const axios = require('axios'); const API_KEY = 'YOUR_API_KEY'; const BASE_URL = 'https://api.asinscope.com/products/lookup'; async function lookupByUpc(upcs, domain = 'com') { const params = new URLSearchParams({ upc: upcs.join(','), domain, }); const url = `${BASE_URL}?${params.toString()}`; const response = await axios.get(url, { headers: { 'x-api-key': API_KEY }, timeout: 30000, }); return response.data; } (async () => { try { const data = await lookupByUpc(['631102001550', '653485442904']); data.items.forEach(item => { console.log(item.upc, item.title); }); } catch (err) { const error = err.response?.data; if (error?.code === 'TOKEN_BUCKET_EMPTY') { console.error(`Bucket empty: retry in ${error.retryAfterSeconds} seconds.`); } else if (error?.code === 'DAILY_LIMIT_REACHED') { console.error('Daily limit reached: stop until 00:00 UTC.'); } else { console.error('Request failed:', err.message); } } })(); ``` ## Tips - Send at most 10 codes per call and use only one identifier type (`asin`, `upc`, or `ean`) per request. - Always specify `domain` if you target a marketplace other than `com`. - URL-encode query parameters; using `curl --get --data-urlencode` helps avoid encoding issues. - On a `429`, read `code`: wait `retryAfterSeconds` and retry for `TOKEN_BUCKET_EMPTY`, stop until the reset for `DAILY_LIMIT_REACHED`. - Don't retry `400`, `401` or `403`: they won't succeed until the request, key or subscription changes. - UPC/EAN lookups are charged per listing returned, so a barcode shared by many listings can cost far more than one token. Prefer ASIN lookups where you already know the ASIN, and watch `consumedTokens` to spot expensive barcodes. --- # AI Integration Guide ## What this is A practical guide for building on the ASINScope API with AI coding tools. The API is plain REST with JSON responses, which LLMs handle well. But AI-written code that is technically correct is often wrong for this API in small ways: it treats a barcode lookup as one token, retries limits that won't reset for hours, or matches results by array position. The recipes and rules below close that gap. For the formal contract, give your assistant the OpenAPI spec: ```text https://docs.asinscope.com/openapi.json ``` The full reference, including this guide, is also available as one plain-text file at [https://docs.asinscope.com/llms-full.txt](https://docs.asinscope.com/llms-full.txt). **Don't want to write code?** Connect your assistant to the [ASINScope MCP server](https://docs.asinscope.com/asinscope-api/mcp/) and ask for lookups in plain language. This guide is for building your own integration on the REST API. ## 5-minute quickstart Subscribe to an API plan and copy your key from the [API dashboard](https://asinscope.com/en/dashboard/api), then set it in your environment: ```bash export ASINSCOPE_API_KEY="your-api-key" ``` Run one request: ```bash curl --get 'https://api.asinscope.com/products/lookup' \ -H "x-api-key: $ASINSCOPE_API_KEY" \ --data-urlencode "asin=B088H39PXX" \ --data-urlencode "domain=com" ``` You get the product plus your token state (trimmed here; the [reference](https://docs.asinscope.com/asinscope-api/) lists every field): ```json { "items": [ { "asin": "B088H39PXX", "upc": "793610399007", "ean": "0793610399007", "upcList": ["793610399007"], "eanList": ["0793610399007"], "mpn": "2143", "brand": "CUKU", "title": "Magnetic Dart Board - 12pcs Magnetic Darts (Red Green Yellow) - ...", "bsr": 95, "lowestNewPrice": 22.79 } ], "dailyTokensLeft": 9998, "bucketSize": 119, "msBeforeNextDailyToken": 82524143, "consumedTokens": 1 } ``` That's the contract. Every successful lookup tells you what it cost (`consumedTokens`), what is left for today (`dailyTokensLeft`) and what is left in the short-term bucket (`bucketSize`). Read them on every call instead of asking for your balance separately. ## Endpoints | Job | Request | Use it for | |---|---|---| | Look up products | `GET /products/lookup?asin=…&domain=…` | ASIN to UPC/EAN/MPN, title, brand, price, BSR, images | | Look up by barcode | `GET /products/lookup?upc=…` or `?ean=…` | UPC/EAN to ASIN(s) and product details | | Check your balance | `GET /account/tokens` | Free check before starting a job (costs no tokens) | Authentication is the `x-api-key` header on every request. Send exactly one of `asin`, `upc` or `ean`, with up to 10 comma-separated codes. ## Prompt recipes Paste one of these into your AI tool and adjust the inputs. Each names the spec URL first so the assistant works from the real schema. Recipes are in English on purpose: they're written for the AI, not for a reader. ### Bulk ASIN to UPC/EAN enrichment ```text Build a script that adds UPC and EAN codes to a CSV of Amazon ASINs using the ASINScope API. OpenAPI spec: https://docs.asinscope.com/openapi.json Base URL: https://api.asinscope.com Auth: API key in the `x-api-key` header, read from the env var ASINSCOPE_API_KEY. Endpoints: GET /account/tokens (free), GET /products/lookup?asin=ASIN1,ASIN2,...&domain=com Input: products.csv with an `asin` column and an optional `domain` column (default com). Output: products_enriched.csv with the original columns plus upc, ean, upc_list, ean_list, title, brand. Rules: - Send at most 10 ASINs per request, all for the same domain, joined with commas. - Match results back to rows by `asin`. Don't rely on the order of `items`. An ASIN with no matching item (or an item without a title) is "not found": leave its columns empty. - upc_list and ean_list hold every barcode Amazon lists for the product; join them with "|". - Once at startup, call GET /account/tokens and keep `tokensPerMinute`. - After each response, read `dailyTokensLeft`. Save progress and exit if it drops below 50. - After each response, read `bucketSize`. If it is below 10, sleep ceil((10 - bucketSize) * 60 / tokensPerMinute) seconds before the next request. - On HTTP 429, read `code` from the JSON body (never match on the message text): TOKEN_BUCKET_EMPTY: sleep `retryAfterSeconds` from the body, then retry the same batch. DAILY_LIMIT_REACHED: save progress and exit. The limit resets at 00:00 UTC. - Never retry 400, 401 or 403. Print the response body and stop. - Make the script resumable: skip rows that already have a result. ``` ### Supplier price list: UPC to ASIN with a token budget ```text Build a tool that matches a supplier's price list (UPC/EAN barcodes) to Amazon ASINs using the ASINScope API. OpenAPI spec: https://docs.asinscope.com/openapi.json Base URL: https://api.asinscope.com Auth: API key in the `x-api-key` header, read from the env var ASINSCOPE_API_KEY. Endpoint: GET /products/lookup?upc=UPC1,UPC2,...&domain=com (or ean=... for EAN-13 codes) Input: supplier.csv with columns barcode, cost. Read barcode as a string, never as a number. Output: matches.csv with one row per (barcode, asin): barcode, cost, asin, title, brand, lowest_new_price, bsr, sold_by_amazon. Barcodes with no match get one row with an empty asin. Rules: - Normalize barcodes first: keep digits only. Send 12-digit codes as `upc` and 13-digit codes as `ean`, in separate requests. Report codes of any other length as invalid without sending them. - One barcode can match several listings, and EACH listing returned costs one token. A single UPC can cost 50+ tokens. - Take a token budget as a CLI argument (default 500). Keep a running total of `consumedTokens` from every response. Before each request, stop if the running total plus the number of codes in the batch would exceed the budget. The real cost is only known after the response, so use batches of 5 when the budget is tight. - Flag any batch whose consumedTokens is more than 3x the number of codes sent as "ambiguous barcodes". - Match items back to barcodes through `upcList` and `eanList` (compare as digits, left-padded with zeros to 14), never by position. - On HTTP 429, read `code` from the JSON body: TOKEN_BUCKET_EMPTY means sleep `retryAfterSeconds` and retry; DAILY_LIMIT_REACHED means stop. - Never retry 400, 401 or 403. ``` ### Queue worker that checks tokens before taking a job ```text Build a worker that processes ASIN lookup jobs from a queue without losing jobs when tokens run out, using the ASINScope API. OpenAPI spec: https://docs.asinscope.com/openapi.json Base URL: https://api.asinscope.com Auth: API key in the `x-api-key` header, read from the env var ASINSCOPE_API_KEY. Endpoints: - GET /account/tokens (free, never consumes tokens) - GET /products/lookup?asin=...&domain=... Each message is JSON: {"asins": ["B0...", ...up to 10], "domain": "de"}. Loop: 1. Before taking a message, call GET /account/tokens. - If dailyTokensLeft < 10: don't take a message. Sleep min(msBeforeNextDailyReset, 15 minutes), then re-check. - If minutelyTokensLeft < 10: sleep ceil((10 - minutelyTokensLeft) * 60 / tokensPerMinute) seconds, then re-check. 2. Take one message, call /products/lookup, store the items, then ack the message. 3. If the lookup still returns 429, requeue the message (nack) and go back to step 1. 4. On 400, send the message to a dead-letter queue. On 401 or 403, stop the worker and alert: the key or subscription is the problem, and retrying won't fix it. 5. On 5xx or a network error, retry up to 3 times with exponential backoff, then requeue. ``` ### Catalog check against Amazon's barcodes ```text Build a catalog validator that checks whether our product barcodes match what Amazon lists for each ASIN, using the ASINScope API. OpenAPI spec: https://docs.asinscope.com/openapi.json Base URL: https://api.asinscope.com Auth: API key in the `x-api-key` header, read from the env var ASINSCOPE_API_KEY. Endpoint: GET /products/lookup?asin=...&domain=... Input: catalog.csv with columns sku, asin, our_barcode, domain. Read every column as a string. Output: report.csv with columns sku, asin, our_barcode, status, amazon_upc_list, amazon_ean_list. Rules: - Look ASINs up in batches of up to 10 per domain. Leave `desc` unset: this job doesn't need descriptions. - Normalize both sides to digits only and left-pad with zeros to 14 digits before comparing, so a UPC-A (12 digits) and the same code as EAN-13 (leading 0) compare equal. - status = "match" if our_barcode is in upcList or eanList after normalizing, "mismatch" if the ASIN was found but our barcode isn't listed, "not_found" if the ASIN has no matching item. - Compare against upcList/eanList, not only the single `upc`/`ean` fields: a listing can carry several barcodes. - Read `dailyTokensLeft` after each response and stop below 50. ``` ## Wiring it into AI tools The same short rule set works in every tool. Paste it where your tool keeps project instructions: ```markdown When working with the ASINScope API: - Spec: https://docs.asinscope.com/openapi.json (plain-text reference: https://docs.asinscope.com/llms-full.txt) - Base URL: https://api.asinscope.com - Auth: `x-api-key` header, value from the env var ASINSCOPE_API_KEY. Never hard-code the key. - GET /products/lookup: exactly one of asin, upc, ean (comma-separated, at most 10 per request); optional domain (default com; also ca, de, fr, it, nl, es, in, uk, jp, au, mx, pl); optional desc=1 for description and bullets. - GET /account/tokens: free balance check (dailyTokensLeft, minutelyTokensLeft, tokensPerMinute, msBeforeNextDailyReset). - Every successful lookup returns dailyTokensLeft, bucketSize and consumedTokens. Read them instead of polling /account/tokens after each call. - UPC/EAN lookups cost one token per listing returned, so one barcode can cost many tokens. Check consumedTokens. - Match items by asin, upcList or eanList, never by array position. - Every 4xx error body has a stable `code`. Branch on it, never on the message text. - 429 DAILY_LIMIT_REACHED: stop until 00:00 UTC. 429 TOKEN_BUCKET_EMPTY: wait `retryAfterSeconds` (also sent as the Retry-After header), then retry. Never retry 400, 401 or 403. ``` - **Claude Code**: add the block as a section of `CLAUDE.md` at the project root, or pass the spec URL in your prompt. Claude Code fetches the spec when it first needs it. - **Cursor**: save the block as `.cursor/rules/asinscope.mdc`. - **ChatGPT, Claude.ai, Gemini**: paste the spec URL or the `llms-full.txt` URL into the conversation and ask the assistant to read it before writing code. - **Other agents** (Windsurf, Cline, Codex CLI, Continue): anything that can fetch a URL or read an OpenAPI document works the same way. Point it at the spec and reuse the recipes above. ## Patterns to imitate ### Quota-aware loops Every successful lookup returns your balance, so there is nothing else to call between requests: ```python for batch in batches: # each batch: up to 10 codes data = lookup(batch) # raises on any non-200 response store(data["items"]) if data["dailyTokensLeft"] < DAILY_FLOOR: break # resume after 00:00 UTC ``` ### Pacing to the short-term bucket Each plan has a bucket that refills continuously (Basic: 60 tokens, refilling 10 per minute; Pro: 120 tokens, refilling 60 per minute). `bucketSize` in each response is what is left in it. Read `tokensPerMinute` from `GET /account/tokens` once, then sleep only when the next batch wouldn't fit: ```python shortfall = BATCH_SIZE - data["bucketSize"] if shortfall > 0: time.sleep(math.ceil(shortfall * 60 / tokens_per_minute)) ``` ### Check before you take work `GET /account/tokens` costs nothing. Call it before pulling a job off a queue, so a job is never taken and then dropped because the daily limit ran out halfway. ### Telling the two 429s apart Both limits return HTTP 429. The `code` says which one it is, and `retryAfterSeconds` (also sent as the `Retry-After` header) says how long it lasts: ```json { "statusCode": 429, "message": "Daily limit reached. Please try again in 312 minutes", "error": "Too Many Requests", "code": "DAILY_LIMIT_REACHED", "retryAfterSeconds": 18720 } ``` ```json { "error": "Not enough tokens in the bucket. Restore rate: 10 / min", "code": "TOKEN_BUCKET_EMPTY", "retryAfterSeconds": 60 } ``` ```python if response.status_code == 429: error = response.json() if error["code"] == "TOKEN_BUCKET_EMPTY": time.sleep(error["retryAfterSeconds"]) # then retry the same request else: # DAILY_LIMIT_REACHED save_progress_and_stop() # resets at 00:00 UTC ``` ## Pitfalls AI-written code commonly hits - **Treating a barcode lookup as one token per code.** UPC/EAN lookups cost one token per listing returned. A UPC shared by 56 listings costs 56 tokens in one request. Read `consumedTokens`. - **Forgetting `domain`.** Without it, every request goes to amazon.com. Pass it explicitly for every other marketplace. - **Sending `desc=1` by default.** It adds descriptions and bullet points and makes responses much larger. Use it only when you need the listing copy. - **Retrying a daily 429.** It won't clear until 00:00 UTC. Only the bucket 429 is worth retrying after a short wait. - **Retrying 400, 401 or 403.** Bad parameters, a bad key or an inactive subscription won't fix themselves. - **Mixing identifier types or sending too many codes.** One of `asin`, `upc`, `ean` per request, at most 10 codes; anything else is a 400. - **Losing leading zeros.** Barcodes read as numbers (or opened in Excel) drop leading zeros, and a UPC-A is the same product as the EAN-13 with a leading 0. Keep barcodes as strings and compare them left-padded to 14 digits. - **Matching by array position.** Match items to your codes by `asin`, `upcList` or `eanList`. - **Matching on error text.** Messages may change. Every 4xx error body has a stable `code`; branch on that. - **Putting the key in the URL.** `?key=` still works, but URLs end up in logs. Send the `x-api-key` header. ## Next - [OpenAPI spec](https://docs.asinscope.com/openapi.json): the machine-readable contract. - [API reference](https://docs.asinscope.com/asinscope-api/): parameters, response fields, limits and code samples. - [MCP server](https://docs.asinscope.com/asinscope-api/mcp/): let Claude, Cursor and other assistants call ASINScope directly. - [Plans and pricing](https://asinscope.com/en/asin-to-upc-api): Basic, Pro and Enterprise API plans. --- # MCP Server The ASINScope MCP server lets an AI assistant look up Amazon products for you. Once it is connected you can ask things like "find the UPCs for these 20 ASINs" or "which ASINs sell this barcode on amazon.de?" and the assistant calls ASINScope itself. There is no code to write. It uses the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), an open standard that Claude, Cursor and many other AI tools support. ```text https://api.asinscope.com/mcp ``` You need an API key from the [API dashboard](https://asinscope.com/en/dashboard/api). The server uses the same key, the same plan and the same tokens as the REST API: a lookup made through an assistant costs exactly what the same lookup costs over REST. ## Connect your assistant ### Claude Code ```bash claude mcp add --transport http asinscope https://api.asinscope.com/mcp \ --header "x-api-key: YOUR_API_KEY" ``` ### Cursor Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for all projects: ```json { "mcpServers": { "asinscope": { "url": "https://api.asinscope.com/mcp", "headers": { "x-api-key": "YOUR_API_KEY" } } } } ``` ### Other clients Any client that supports MCP over Streamable HTTP works. Give it the server URL and send your key in the `x-api-key` header. Some apps only let you enter a server URL, with no place for a header. For those, put the key in the URL: ```text https://api.asinscope.com/mcp?key=YOUR_API_KEY ``` A key in a URL is easier to leak (it can end up in logs and screenshots), so use the header wherever the client supports it. ## Tools | Tool | What it does | Cost | |---|---|---| | `lookup_products` | Looks up products by ASIN, UPC or EAN on one Amazon marketplace. Returns UPC/EAN codes, MPN, title, brand, category, Best Sellers Rank, lowest new price, package dimensions and images | Tokens, same as `GET /products/lookup` | | `get_token_balance` | Shows tokens left today, the daily allowance and the short-term bucket | Free | `lookup_products` takes: - `asins`, `upcs` or `eans`: a list of codes. Exactly one of the three, with up to 10 codes per call on Basic and Pro plans. - `domain` (optional): the marketplace. Defaults to `com`. Also `ca`, `de`, `fr`, `it`, `nl`, `es`, `in`, `uk`, `jp`, `au`, `mx`, `pl`. - `include_description` (optional): also return the listing description and bullet points. The results are the same JSON the REST API returns, including `consumedTokens` and `dailyTokensLeft`, so the assistant can tell you what each request cost. ## Things to know - **Barcode lookups can cost more than one token per code.** A UPC or EAN costs one token per listing returned, and a barcode can be shared by many listings. Ask the assistant to check the balance first when you hand it a long list. - **Big lists take several calls.** The assistant sends up to 10 codes at a time, and each plan has a short-term bucket (see [Rate Limits](https://docs.asinscope.com/asinscope-api/#rate-limits)). When the bucket is empty the server says how long to wait, and the assistant can continue after that. - **Limits and errors are the REST API's.** A tool call that fails returns the same error body with the same `code` as the [REST API](https://docs.asinscope.com/asinscope-api/), for example `TOKEN_BUCKET_EMPTY` or `DAILY_LIMIT_REACHED`. - **Not found still costs a token.** A code that matches nothing on the chosen marketplace is charged like any other. ## Example requests Once connected, you can ask in plain language: - "Convert these ASINs to UPC and EAN and give me a table: B088H39PXX, B01NAL48FU." - "Which ASIN has the UPC 793610399007 on amazon.com, and what is its current lowest new price?" - "How many ASINScope tokens do I have left today?" - "Here is my supplier's price list. Match each UPC to an Amazon ASIN, and stop if it would cost more than 200 tokens." ## Troubleshooting - **"No ASINScope API key was sent"**: the client connected without a key. Add the `x-api-key` header to the server configuration, or use the URL form with `?key=`. - **`INVALID_API_KEY`**: the key is wrong. Copy it again from the API dashboard. - **`NO_ACTIVE_SUBSCRIPTION`**: the key has no active API plan. See [plans and pricing](https://asinscope.com/en/asin-to-upc-api). - **The assistant doesn't see the tools**: restart the client after changing its MCP configuration, and check that the URL ends in `/mcp`. Building your own integration instead? See the [AI integration guide](https://docs.asinscope.com/asinscope-api/ai/) and the [OpenAPI spec](https://docs.asinscope.com/openapi.json).