ASIN lookup in practice

An ASIN — Amazon Standard Identification Number — is the ten-character alphanumeric code Amazon assigns to a product listing on a specific storefront, formatted like B08N5WRWNW. It's not a universal product identifier the way a UPC or ISBN aims to be: it's scoped to the storefront that issued it, so the same physical product sold on amazon.com and amazon.de can, and often does, carry two different ASINs. Once you have an ASIN for the market you're targeting, it's the key that unlocks everything else in CatalogAIO's product surface — details, offers, reviews, and its place on a best-seller list.

Every endpoint that takes an ASIN validates its shape before doing anything else: ten alphanumeric characters, nothing more, nothing less. Pass something shorter, longer, or with the wrong characters and you get a validation error back immediately, without a wasted round trip to the storefront — which matters if you're generating candidate ASINs programmatically rather than typing them by hand.

From keyword to ASIN

If you don't have an ASIN yet, GET /v1/search is where you start: pass a keyword query, optionally a page (1–20), a department category, and a domain or country to pick the storefront. Each result card comes back with an asin field alongside title and price, so a search response is already a list of ASINs you can feed straight into the endpoints below.

curl -s "https://catalog.apexon.dev/v1/search?query=usb-c+hub&page=1" \
  -H "X-API-Key: YOUR_KEY"

GET /v1/suggestions is a different tool for a different job: give it a prefix and it returns Amazon's own autocomplete completions — plain query text, not products or ASINs — so it's useful for building a search-as-you-type box, not for resolving an identifier. Reach for search when you need ASINs; reach for suggestions when you need what a shopper would type next.

Product details

GET /v1/product/{asin} is the workhorse: full listing detail — title, images, description, price, rating — for one ASIN on one storefront. domain and country pick the storefront the same way they do on search; leave both off and you get the default US catalog on amazon.com.

curl -s "https://catalog.apexon.dev/v1/product/B08N5WRWNW?country=DE" \
  -H "X-API-Key: YOUR_KEY"

That's the call you'd make once you already know which ASIN you want and need everything about it in one shot — a product page render, a catalog sync, a one-off lookup during support triage.

Offers: who is selling and for how much?

GET /v1/product/{asin}/offers returns the buy-box and third-party offer listing for an ASIN — who's currently selling it and at what price, separate from the single "current price" field on the product-details response. It takes the same domain/country pair as the other product routes.

curl -s "https://catalog.apexon.dev/v1/product/B08N5WRWNW/offers" \
  -H "X-API-Key: YOUR_KEY"

Use this when the question isn't "what does this product cost" but "who's competing for the buy box and at what price" — repricing tools and competitive-monitoring dashboards are the typical callers.

Reviews

GET /v1/product/{asin}/reviews returns customer reviews for an ASIN, paged with page (1–20) and ordered by sort_by — recent or helpful, defaulting to recent. There's no page-size parameter to change how many reviews come back per page; page through with page if you need more than the first batch.

curl -s "https://catalog.apexon.dev/v1/product/B08N5WRWNW/reviews?page=2&sort_by=helpful" \
  -H "X-API-Key: YOUR_KEY"

This is what feeds review-monitoring and sentiment pipelines — watching for a rating drop, or pulling the most-helpful reviews to summarize what buyers actually say about a listing.

Best sellers by category

GET /v1/bestsellers returns a ranked list rather than a single ASIN's data — pass a category (e.g. electronics) and a type (zgbs, new-releases, or movers-and-shakers, defaulting to zgbs) plus the usual domain/country. Each item in the list carries its own asin, so a best-sellers call doubles as a way to discover ASINs you didn't already have.

curl -s "https://catalog.apexon.dev/v1/bestsellers?category=electronics&type=new-releases" \
  -H "X-API-Key: YOUR_KEY"

Reach for this when you're tracking category rank over time, sourcing candidate products for a niche, or watching what's newly trending rather than looking up something you already identified.

Watch your plan headers

CatalogAIO's free BASIC plan covers the core surface — search, product details, suggestions, and markets. Offers, reviews, and best sellers are gated to PRO and above, and that split is enforced server-side on every request to those three routes (plus their marketplace-alias equivalents), before the rate limiter even runs, so a denied call never spends any of your quota.

Call a gated endpoint on a BASIC key and you get a 403 back, not partial or empty data:

curl -s "https://catalog.apexon.dev/v1/product/B08N5WRWNW/offers" \
  -H "X-API-Key: YOUR_BASIC_KEY"

{
  "success": false,
  "error": {
    "code": "plan_upgrade_required",
    "message": "The offers endpoints are not included in the basic plan. Upgrade to PRO or above to enable them.",
    "status": 403,
    "details": {"feature": "offers", "plan": "basic", "required_plan": "pro"}
  },
  "request_id": "9f3c1a2b8d4e"
}

Every response, allowed or refused, also carries an X-Plan header naming the plan your key resolved to — a quick way to confirm which tier you're actually calling as without checking a dashboard. If you're building against offers, reviews, or best sellers, branch on error.code rather than assuming a 200 with data: a caught plan_upgrade_required is a cheap check, a pipeline that expects offers on every call and instead gets an error body is not.

FAQ

Are ASINs the same in every country?

No — ASINs are assigned per storefront, so the same physical product can carry a different ASIN on amazon.com than it does on amazon.de or amazon.co.uk. Query the storefront you actually care about — pass domain=amazon.de or country=DE (or any of the other supported markets) — rather than assuming an ASIN you found on one storefront resolves the same way on another.

Can I fetch multiple ASINs in one call?

No — there's no batch route. /v1/product/{asin} and its offers and reviews siblings all take exactly one ASIN in the path, and the marketplace aliases take asin as a single query parameter, not a list. If you have a list of ASINs to look up, that's one call per ASIN — fan them out concurrently on your side, within your rate limit, rather than waiting for a batch endpoint that doesn't exist.

Why does my offers call return a plan error?

Offers, reviews, and best sellers require a PRO plan or higher; search, product details, suggestions, and markets all work on the free BASIC plan. If a call to offers, reviews, or bestsellers comes back 403 plan_upgrade_required, that's the gate working as designed, not a bug — error.details names exactly which feature and which plan tier you need.

What identifiers does search return?

Each result card in a search response includes an asin field alongside title, price, and the other listing fields — the same identifier you feed straight into /v1/product/{asin} and its offers and reviews siblings. Suggestions doesn't return ASINs at all; it's autocomplete text for refining your query, not a list of products.