To find the Amazon category of an ASIN, call /api/amazon-product-lookup and read productInfo.categories: the product page's category breadcrumb, root first, with a browse node ID, name and URL for every step. One lookup costs 1 credit. Before you send one of those IDs to the bestsellers endpoint, check it against the marketplace's free category tree: the root step's ID does not match its top level, which uses slugs, and an unknown category_id is a free 400, checked before the credit is taken.
Key Takeaways
- productInfo.categories holds the breadcrumb: rootCategory plus a bestsellerCategory list ordered by index, each step with a browse node id, name and url.
- Without a breadcrumb on the page, categories is an empty list [], not an empty object, so test the type before reading keys.
- The root step's numeric ID (468642 for Video Games on amazon.com) is not a valid category_id: the category tree uses slugs such as videogames at the top level.
- Use the deepest breadcrumb node that exists in the category tree; an unknown category_id on /amazon-bestsellers is a free 400 Invalid CategoryId, checked before the credit is taken.
- The tree file is free, so the check costs nothing; one bestsellers call per category serves every ASIN in it.
What does productInfo.categories return?
The lookup returns two category fields. categories is the breadcrumb Amazon shows above the product, for example Video Games > PlayStation 5 > Consoles, with the browse node ID of every step. bestsellerRanks is the separate Best Sellers Rank line: a rank and a category name, but no ID. The two blocks come from different parts of the page, so their names do not have to match: the documented PlayStation 5 response ranks #1 in a subcategory named PlayStation, while its breadcrumb ends in Consoles. Join them by meaning, never by name.
| Field | Type | What it holds |
|---|---|---|
categories.rootCategory | object | First breadcrumb step: id (browse node), name, url |
categories.bestsellerCategory[] | list | The steps below the root, each with index (1, 2, ...), id, name, url |
categories (no breadcrumb) | [] | An empty list, not an empty object: check the type first |
bestsellerRanks.main_category | object | name and rank as the page shows them; rank 0 and name empty when no rank is shown |
bestsellerRanks.subcategory | object | Only present when the page shows a second rank |
The two category fields of the documented B0CL61F39H lookup on amazon.com (trimmed)
{
"success": true,
"data": {
"productInfo": {
"asin": "B0CL61F39H",
"bestsellerRanks": {
"main_category": {
"name": "Video Games",
"rank": 31
},
"subcategory": {
"name": "PlayStation",
"rank": 1
}
},
"categories": {
"bestsellerCategory": [
{
"id": "20972781011",
"index": 1,
"name": "PlayStation 5",
"url": "https://www.amazon.com/b/ref=dp_bc_2?ie=UTF8&node=20972781011"
},
{
"id": "20972796011",
"index": 2,
"name": "Consoles",
"url": "https://www.amazon.com/b/ref=dp_bc_3?ie=UTF8&node=20972796011"
}
],
"rootCategory": {
"id": "468642",
"name": "Video Games",
"url": "https://www.amazon.com/computer-video-games-hardware-accessories/b/ref=dp_bc_1?ie=UTF8&node=468642"
}
}
}
}
}
Why does the root category ID fail on the bestsellers endpoint?
/api/amazon-bestsellers only accepts a category_id that exists in that marketplace's category tree, the same tree the category explorer shows. Its top level uses short slugs such as videogames or electronics; numeric browse node IDs only start one level down. The breadcrumb's root step is a numeric node (468642 for Video Games), so it never matches a top-level entry. Every other ID is worth checking too, because an ID the tree does not know is answered with the free 400 Invalid CategoryId, for no credit. How the tree files are organised is covered in how to find Amazon category IDs.

Check one ASIN by hand: download the tree once, print the breadcrumb, test two IDs
# 1. Once: the amazon.com category tree (a public file: no API key, no credit)
curl -s -o US.json https://sellermagnet-api.com/static/data/US.json
# 2. One lookup (1 credit): the breadcrumb, root first
curl -sG "https://sellermagnet-api.com/api/amazon-product-lookup" \
-H "X-Api-Key: $SELLERMAGNET_API_KEY" \
--data-urlencode "asin=B0CL61F39H" --data-urlencode "marketplaceId=ATVPDKIKX0DER" \
| jq -r '.data.productInfo.categories
| if type == "object"
then ([.rootCategory] + (.bestsellerCategory | sort_by(.index))) | .[] | "\(.id) \(.name)"
else "no breadcrumb on this page" end'
# 3. Is a node in the tree? 1 = usable as category_id, 0 = a free 400 on /amazon-bestsellers (no credit)
for id in 468642 20972796011; do
echo "$id $(jq --arg id "$id" '[.. | objects | select(.CategoryId? == $id)] | length' US.json)"
done
How do I get the category of many ASINs in Python?
The script below does the same for a list of ASINs. It uses get_with_retry from retry.py and new_session and ApiError from sellermagnet.py, both from the Python quickstart. It filters bad ASINs before paying for them, reads the breadcrumb (object or empty list), picks the deepest node that is in the downloaded tree, and then makes one count=50 bestsellers call per category to show where each ASIN sits in that list right now. Two ASINs in the same category share that call.
category_path.py: ASIN to category path, category_id and top 50 position
"""Find the Amazon category of each ASIN and turn it into a valid category_id for the bestsellers endpoint.
One /amazon-product-lookup call per ASIN (1 credit). productInfo.categories is the product page's breadcrumb,
root first, with a browse node ID per step. Every ID is checked against the marketplace's public category tree
(a free download, no credit) before it goes to /amazon-bestsellers, because an unknown category_id there is a
free 400 too, checked before the credit is taken. Helpers: sellermagnet.py and retry.py from the Python quickstart post.
"""
import json
import re
import requests
from retry import get_with_retry
from sellermagnet import ApiError, new_session
MARKETPLACE = "ATVPDKIKX0DER" # amazon.com
TREE_FILE = "US.json" # the amazon.com category tree, downloaded once (see the curl line)
ASINS = ["B0CL61F39H", "B0EXAMPLE1", "B0EXAMPLE2", "B0EXAMPLE3", "B0EXAMPLE4"]
CHECK_TOP_50 = True # one bestsellers call per category: where does the ASIN sit right now?
MAX_FAILED = 3 # stop after this many failed lookups instead of paying for more
ASIN_RE = re.compile(r"^[A-Z0-9]{10}$")
def load_tree(path: str) -> dict:
"""category_id -> names from the top level down, for every node of the tree (first place it appears)."""
index = {}
def walk(nodes, names):
for node in nodes:
here = names + [node["CategoryName"]]
index.setdefault(str(node["CategoryId"]), here)
walk(node.get("Subcategories") or [], here)
with open(path, encoding="utf-8") as f:
walk(json.load(f), [])
return index
def breadcrumb(product: dict) -> list:
"""[(node_id, name), ...] root first. categories is [] (a list, not an object) when the page has no
breadcrumb, so check the type before reading keys."""
cats = product.get("categories")
if not isinstance(cats, dict):
return []
steps = [cats.get("rootCategory") or {}]
steps += sorted(cats.get("bestsellerCategory") or [], key=lambda c: c.get("index", 0))
# the id is cut out of the breadcrumb link: drop anything after it, should a link carry more parameters
return [(str(s["id"]).split("&")[0], s.get("name", "")) for s in steps if s.get("id")]
def bestseller_id(steps: list, tree: dict):
"""Deepest breadcrumb node the category tree knows. The root never matches: the tree's top level uses
slugs such as 'videogames', the breadcrumb a numeric node."""
for node_id, _ in reversed(steps):
if node_id in tree:
return node_id
return None
def clean_asins(raw: list) -> list:
"""Upper-case, drop duplicates and anything that is not 10 letters/digits: the lookup does not validate
the format, so a typo would be a billed call."""
seen, out = set(), []
for value in raw:
asin = str(value).strip().upper()
if not ASIN_RE.match(asin):
print(f"skip {value!r}: not an ASIN, no call made")
elif asin not in seen:
seen.add(asin)
out.append(asin)
return out
def main():
tree = load_tree(TREE_FILE)
session = new_session()
rows, failed, lookups = [], 0, 0
for asin in clean_asins(ASINS):
lookups += 1
try:
product = get_with_retry(session, "amazon-product-lookup", asin=asin,
marketplaceId=MARKETPLACE)["productInfo"]
except ApiError as err:
if err.status in (401, 403) or (err.status == 400 and "marketplace" in str(err).lower()):
raise # key, credits or marketplace: every next call would fail the same way
rows.append({"asin": asin, "error": f"error {err}"})
failed += err.status != 404 # a 404 is an answer (no such product), not a failure to retry
except requests.RequestException as err:
rows.append({"asin": asin, "error": f"no answer ({type(err).__name__}), try again later"})
failed += 1
else:
steps = breadcrumb(product)
node = bestseller_id(steps, tree)
rank = (product.get("bestsellerRanks") or {}).get("main_category") or {}
rows.append({"asin": asin, "steps": steps, "node": node,
"leaf_in_tree": bool(steps) and node == steps[-1][0],
"bsr": f"#{rank['rank']} {rank.get('name', '')}" if rank.get("rank") else "-"})
if failed >= MAX_FAILED:
print(f"stopped after {failed} failed lookups")
break
spots, calls = {}, 0
if CHECK_TOP_50:
for node in sorted({r["node"] for r in rows if r.get("node")}):
calls += 1 # one call per category, however many of your ASINs sit in it
try:
cards = get_with_retry(session, "amazon-bestsellers", category_id=node,
marketplaceId=MARKETPLACE, count=50)["bestsellers"]
spots[node] = {c.get("asin"): c.get("rank") for c in cards if c.get("asin")}
except ApiError as err:
spots[node] = f"error {err.status}"
except requests.RequestException:
spots[node] = "no answer"
for r in rows:
if "error" in r:
print(f"{r['asin']} {r['error']}")
continue
if not r["steps"]:
print(f"{r['asin']} no breadcrumb on the page, nothing to map (BSR {r['bsr']})")
continue
print(f"{r['asin']} {' > '.join(name for _, name in r['steps'])} (BSR {r['bsr']})")
if not r["node"]:
print(" no breadcrumb node is in the category tree: no bestsellers call")
continue
leaf, used = r["steps"][-1][1], tree[r["node"]][-1]
note = "" if r["leaf_in_tree"] else f" ({leaf} is not in the tree, parent {used} used)"
top = spots.get(r["node"], "not checked")
if isinstance(top, dict):
spot = top.get(r["asin"], "absent")
top = "not in top 50" if spot == "absent" else f"#{spot}" if spot else "listed, no rank shown"
print(f" category_id {r['node']} top 50: {top}{note}")
print(f"lookups {lookups}, bestsellers calls {calls}, credits {lookups + calls} (+1 per billed retry)")
if __name__ == "__main__":
try:
main()
except ApiError as err: # 401/403 or a bad marketplace: nothing else would succeed either
raise SystemExit(f"stopped: {err}")
Output for five ASINs (illustrative data apart from the documented B0CL61F39H breadcrumb)
B0CL61F39H Video Games > PlayStation 5 > Consoles (BSR #31 Video Games)
category_id 20972796011 top 50: #1
B0EXAMPLE1 Video Games > PlayStation 5 > Consoles (BSR #212 Video Games)
category_id 20972796011 top 50: #3
B0EXAMPLE2 Electronics > Accessories & Supplies > Cables > USB Cables (BSR #5120 Electronics)
category_id 12954861 top 50: not in top 50 (USB Cables is not in the tree, parent Cables used)
B0EXAMPLE3 no breadcrumb on the page, nothing to map (BSR -)
B0EXAMPLE4 error 404: Invalid product
lookups 5, bestsellers calls 2, credits 7 (+1 per billed retry)

What does it cost?
1 credit per request, with the usual rules: a 404 for an ASIN that does not exist is billed, a free gate 400 (missing parameter, unknown marketplaceId) is not, a 500 without Retry-After is refunded, and a 502 or 503 is billed on every attempt. The lookup does not validate the ASIN format, so the script drops anything that is not 10 letters or digits before it pays, and stops after three failed lookups instead of retrying a broken list forever.
| Step | Credits | Note |
|---|---|---|
| Download the category tree file | 0 | A public file, no API key, re-download when you need fresh data |
One /api/amazon-product-lookup per ASIN | 1 each | A 404 for an unknown ASIN is billed too |
One /api/amazon-bestsellers per category | 1 each | Shared by every ASIN in that category |
| Retry after a 502 or 503 | 1 per attempt | A 500 without Retry-After is refunded |
| Example run below (5 ASINs, 2 categories) | 7 | 5 lookups + 2 bestsellers calls, no retries |
What the category data cannot tell you
- One path only.
categoriesis the breadcrumb the product page shows. The API returns no other category assignments for the ASIN. - Names are local. Breadcrumb names are in the marketplace's language, and numeric node IDs differ between marketplaces, so an amazon.de ID is not an amazon.com ID.
- Trees change. Amazon can rename, move or retire categories. Re-download the tree file before a large run; the script reports a free Invalid CategoryId per row if the tree is stale (no credit taken).
- Ranks are not IDs.
bestsellerRanksgives a rank and a name, not a node ID; for the current rank of an ASIN see Amazon BSR by category.
Frequently Asked Questions
How do I find the Amazon category of an ASIN with an API?
Call /api/amazon-product-lookup with the ASIN and marketplaceId and read productInfo.categories: rootCategory plus the bestsellerCategory steps, each with a browse node id, name and url. It costs 1 credit.
Why is productInfo.categories an empty list?
The product page showed no category breadcrumb, so the API returns [] instead of an object. Treat it as no category data, not as an error.
Can I pass the breadcrumb's root ID to the bestsellers endpoint?
No. The category tree uses slugs such as videogames at the top level, so the numeric root ID does not match there; in the documented amazon.com example it is not in the tree at all, a free 400 Invalid CategoryId (checked before the credit is taken). Use the deepest step the tree knows.
Does checking IDs against the category tree cost credits?
No. The tree is a public JSON file per marketplace, for example sellermagnet-api.com/static/data/US.json. Download it once and check IDs locally.
Which tree file do I use for amazon.ie?
The UK tree. amazon.ie has no tree file of its own, and the bestsellers endpoint checks amazon.ie category IDs against the amazon.co.uk tree.
Bottom line: one lookup gives you the category path and its browse node IDs; the free tree file tells you which of them the bestsellers endpoint accepts. Skip the root, take the deepest known step, and make one bestsellers call per category. The product lookup page lists every response field, and a free account includes 150 credits.