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:
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.
Connect your assistant to the ASINScope MCP server 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, then set it in your environment:
export ASINSCOPE_API_KEY="your-api-key"
Run one request:
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 lists every field):
{
"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
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
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
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
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:
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.mdat 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.txtURL 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:
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:
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:
{
"statusCode": 429,
"message": "Daily limit reached. Please try again in 312 minutes",
"error": "Too Many Requests",
"code": "DAILY_LIMIT_REACHED",
"retryAfterSeconds": 18720
}
{
"error": "Not enough tokens in the bucket. Restore rate: 10 / min",
"code": "TOKEN_BUCKET_EMPTY",
"retryAfterSeconds": 60
}
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=1by 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,eanper 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,upcListoreanList. - 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 thex-api-keyheader.
Next
- OpenAPI spec: the machine-readable contract.
- API reference: parameters, response fields, limits and code samples.
- MCP server: let Claude, Cursor and other assistants call ASINScope directly.
- Plans and pricing: Basic, Pro and Enterprise API plans.