REST ENDPOINT POST /api/map/batch

Batch Queue & Jobs

Accepts up to 500 identifiers in a single payload. Items are ingested into the database and processed asynchronously in background worker chunks.

Authentication

AUTH OPTIONS

# Same auth options as POST /api/map - either of:
Authorization: Bearer pm_live_xxxxxxxxxxxxxxxxxxxxxxxx   # personal API key
# ...or a signed-in browser session, no header needed

Initiate Batch Job

HTTP REQUEST

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

{
  "items": [
    "079361039905",
    "4006381333931",
    "B01NAL48FU"
  ],
  "marketplace": "amazon"
}

HTTP 202 RESPONSE

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

{
  "id": "a57f92ba-72c1-4cb5-8d5f-9e7f8e91e0a2",
  "userId": "user_2xyz...",
  "orgId": "org_2abc...",
  "marketplace": "amazon",
  "totalItems": 3,
  "processedItems": 0,
  "matchedItems": 0,
  "status": "processing",
  "createdAt": "2026-08-23T20:45:35.079Z",
  "updatedAt": "2026-08-23T20:45:35.079Z"
}

Poll Status & Export Results

The batch job processes asynchronously in the background. Poll its status by ID, or request a CSV export once it reaches completed.

POLLING

GET /api/jobs/batch/a57f92ba-72c1-4cb5-8d5f-9e7f8e91e0a2

# Same BatchJobSummary shape as above, with an added "items" array once
# processing has started:

{
  ...,
  "items": [
    {
      "id": "b2e1...",
      "identifierType": "UPC",
      "identifierValue": "079361039905",
      "marketplaceId": "B01NAL48FU",
      "title": "Nike Air Zoom Pegasus 36 Men's Running Shoes",
      "brand": "Nike",
      "price": 119.95,
      "formattedPrice": "$119.95",
      "salesRank": 1420,
      "offerCount": 6,
      "imageUrl": "https://m.media-amazon.com/images/I/71xyz.jpg",
      "status": "completed"
    }
  ]
}

# Append ?format=csv to download the results as a CSV file instead of JSON:
GET /api/jobs/batch/a57f92ba-72c1-4cb5-8d5f-9e7f8e91e0a2?format=csv

Batch items carry a smaller field set than a single lookup

Each entry in items is not the same shape as listingDetails from POST /api/map. A batch item only has: identifierType, identifierValue, marketplaceId, title, brand, price, formattedPrice, salesRank, offerCount, imageUrl, and status. Missing compared to a single lookup: manufacturer, description, listPrice, offerCountFba, offerCountMerchant, isBuyBoxWinner, category, categoryGroup, packageQuantity, link, isActive, and identifiers. If you need those fields, look the identifier up individually via POST /api/map once you have its resolved marketplaceId.

Titles are not supported in batch

Every item in items should be a UPC, EAN, GTIN, or ASIN - not a product title. The single-lookup endpoint's title search (see POST /api/map) has no batch equivalent; a title-shaped string sent here isn't rejected, but the app's own UI for pasting/uploading a batch list treats any whitespace as a separator between entries, so a multi-word title gets silently split into several bogus lookups rather than treated as one title search. Stick to barcodes/ASINs for batch.

500 item limit

Requests with more than 500 items are rejected with 400. Split larger lists into multiple batch jobs.

An item gives up after 60 seconds of resolving

Each item gets an 8-second synchronous attempt, then up to 60 more seconds of background polling if it's still resolving. If it still hasn't resolved by then, that item is marked not_found permanently - there's no further polling and no separate jobId for that individual item, so a slow marketplace lookup can come back not_found even though the identifier is genuinely valid. This is rare but worth knowing for large batches.