Card Batch API

Card Batch converts structured card identity fields into precise eBay searches and processes them as a background job. Each completed card uses carryover first, then one monthly request, then one purchased credit after monthly quota is exhausted. Add X-Credit-Source: credits when submitting to fund the whole job from credits first (it falls back to your monthly allowance if credits run out). Failed cards are not charged.

Submit a batch

curl -X POST "https://api.compsniper.com/v1/cards/batch" \
  -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inventory-run-2026-08-31" \
  -d '{
    "cards": [
      {
        "reference": "inventory-001",
        "year": 2023,
        "set": "Topps Chrome",
        "player": "Victor Wembanyama",
        "cardNumber": "1",
        "parallel": "Refractor",
        "grader": "PSA",
        "grade": 10
      },
      {
        "reference": "inventory-002",
        "keyword": "1999 pokemon base set charizard 4/102 psa 9"
      }
    ],
    "options": {
      "count": 60,
      "outputMode": "summary",
      "exactMatch": false,
      "relevance": true
    }
  }'

An explicit keyword overrides generated card fields. Otherwise, combine year, set, subject, player, character, cardNumber, parallel, grader, and grade.

options.exactMatch defaults to false, and that is the right choice for most card searches. Card keywords with a full card number, set name and grade often have no exact matches on eBay, so exactMatch=true can return no sales even for cards that sell often, while the default cleanup already keeps only the right card, parallel and grade. Turn it on only when you need to exclude eBay's Results matching fewer words section and accept fewer results. See exactMatch.

options.bestOfferPrice: true adds the real accepted price to every accepted Best Offer sale in the results (acceptedOfferPrice and acceptedOfferPriceStatus), at no extra cost. See Accepted Best Offer prices.

Poll or cancel

curl -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" \
  "https://api.compsniper.com/v1/cards/batch/JOB_ID"

• GET /v1/cards/batch/:jobId returns progress and completed card results.
• DELETE /v1/cards/batch/:jobId stops unfinished work safely.
• Results remain available for 30 days.
• Reuse an Idempotency-Key when retrying submission after a network failure.

Output modes

• summary: up to 100 cards with cleaned price summaries.
• compact: up to 25 cards and 60 sold rows per card.

Compact rows include bestOfferAccepted. When it is true, eBay marked an accepted Best Offer and the shown price may be above what the buyer paid. Set options.bestOfferPrice: true to add acceptedOfferPrice, the real accepted amount, on US-dollar sales; otherwise exclude those rows when exact transaction price is required.