REST ENDPOINT POST /api/map

Single Barcode Lookup

Synchronously resolves a single UPC, EAN, GTIN, ASIN, or Title. If resolution takes longer than 8 seconds, returns a 202 Accepted with a job ID - see Job Status & Polling for how to pick up the result.

Authentication

Every request needs exactly one of these:

AUTH OPTIONS

# Either of the following:

# 1. Personal API key (generate one at /dashboard/api-keys)
Authorization: Bearer pm_live_xxxxxxxxxxxxxxxxxxxxxxxx

# 2. Browser session (signed in via Clerk) - no header needed, cookies do the work

Request Specification

HTTP REQUEST

POST /api/map
Content-Type: application/json
Authorization: Bearer pm_live_xxxxxxxxxxxxxxxxxxxxxxxx

{
  "type": "UPC",
  "value": "079361039905",
  "marketplace": "amazon",
  "region": "US"
}

# "type" also accepts "auto" (or can be omitted) to infer UPC/EAN/GTIN/ASIN/Title from the value's shape.
# "region" is optional - see "Region Filtering" below.
# Generate a personal API key at /dashboard/api-keys, or use a browser session (signed in via Clerk).

Auto-detect available

Pass "type": "auto", or omit type entirely, to have the server infer UPC/EAN/GTIN/ASIN/Title from the shape of value.

GET /api/map?type=UPC&value=079361039905&marketplace=amazon&region=US works identically to the POST form above, using query parameters instead of a JSON body.

Region Filtering

Optional region parameter restricts the search to one specific Amazon marketplace country instead of every marketplace ProductMapper covers. Accepts: US, CA, MX, BR, UK, DE, FR, IT, ES, NL, PL, SE, IN, JP, AU, SG. An unrecognized region returns 400 rather than silently matching nothing.

Response Specification

listingDetails below is the full set of product and pricing data ProductMapper resolves for a match. Amazon does not expose star ratings or review counts through this data source, so those fields don't exist in this response; anything you don't see here genuinely isn't available, not omitted from the docs.

HTTP 200 RESPONSE

HTTP/1.1 200 OK
Content-Type: application/json

{
  "identifierType": "UPC",
  "identifierValue": "079361039905",
  "marketplace": "amazon",
  "marketplaceId": "B01NAL48FU",
  "amazonMarketplaceLabel": "US",
  "timestamp": 1787503535096,
  "listingDetails": {
    "asin": "B01NAL48FU",
    "title": "Nike Air Zoom Pegasus 36 Men's Running Shoes",
    "brand": "Nike",
    "manufacturer": "Nike Inc.",
    "description": "Lightweight breathable mesh upper. Foam midsole for responsive cushioning. Rubber outsole for durable traction.",
    "imageUrl": "https://m.media-amazon.com/images/I/71xyz.jpg",
    "price": 119.95,
    "formattedPrice": "$119.95",
    "listPrice": 129.95,
    "offerCount": 6,
    "offerCountFba": 4,
    "offerCountMerchant": 2,
    "isBuyBoxWinner": true,
    "salesRank": 1420,
    "category": "Athletic Shoes",
    "categoryGroup": "Sporting Goods",
    "packageQuantity": 1,
    "link": "https://www.amazon.com/dp/B01NAL48FU",
    "isActive": true,
    "identifiers": {
      "upc": "079361039905",
      "asin": "B01NAL48FU"
    },
    "marketplaceId": "ATVPDKIKX0DER",
    "marketplaceLabel": "US"
  }
}

Nullable fields

price, formattedPrice, listPrice, offerCount, offerCountFba, offerCountMerchant, isBuyBoxWinner, and salesRank are all null - never a fabricated placeholder - whenever Amazon doesn't report that data point for the matched listing.

Two marketplaceId/marketplaceLabel pairs - don't confuse them

The top-level marketplaceId is the matched product's ASIN (despite the name); the top-level amazonMarketplaceLabel (e.g. "US", "CA") is the real Amazon marketplace country this result was matched in. Nested inside listingDetails, a separate marketplaceId/marketplaceLabel pair holds Amazon's own internal marketplace identifier (e.g. ATVPDKIKX0DER for US) and its display label - present for most results, but not guaranteed on every match.

Multiple Region Matches

When no region filter is given and the identifier has matches in more than one Amazon marketplace, the response includes a results array - one entry per distinct region match, each with the same shape as the top-level object. The top-level fields always mirror results[0] so every existing integration that only reads the top level keeps working unchanged. A region-scoped request, or an unscoped request with only one matching region, never includes results - just the single object, as in the response above.

HTTP 200 RESPONSE (multi-region)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "identifierType": "UPC",
  "identifierValue": "079361039905",
  "marketplace": "amazon",
  "marketplaceId": "B01NAL48FU",
  "amazonMarketplaceLabel": "US",
  "timestamp": 1787503535096,
  "listingDetails": { "...": "same shape as above - this is the US match" },
  "results": [
    {
      "identifierType": "UPC",
      "identifierValue": "079361039905",
      "marketplace": "amazon",
      "marketplaceId": "B01NAL48FU",
      "amazonMarketplaceLabel": "US",
      "timestamp": 1787503535096,
      "listingDetails": { "...": "..." }
    },
    {
      "identifierType": "UPC",
      "identifierValue": "079361039905",
      "marketplace": "amazon",
      "marketplaceId": "B0C8PVH9FU",
      "amazonMarketplaceLabel": "CA",
      "timestamp": 1787501234000,
      "listingDetails": { "...": "..." }
    }
  ]
}

Queued Response (Slow Resolution)

If resolution hasn't completed within 8 seconds, the request returns immediately with a job ID instead of blocking further. See Job Status & Polling for how to retrieve the result once it's ready.

HTTP 202 RESPONSE

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "status": "processing",
  "message": "Request is queued. You can poll the status endpoint.",
  "jobId": "641a5293-91de-41bb-a019-db228c58f04e"
}

Not Found

Returned when the identifier has no match in Amazon's catalog.

HTTP 404 RESPONSE

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "Product mapping could not be resolved"
}