Skip to main content

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.

Don't want to write code?

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​

JobRequestUse it for
Look up productsGET /products/lookup?asin=…&domain=…ASIN to UPC/EAN/MPN, title, brand, price, BSR, images
Look up by barcodeGET /products/lookup?upc=… or ?ean=…UPC/EAN to ASIN(s) and product details
Check your balanceGET /account/tokensFree 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.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:

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=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​