API reference

Amazon Scraper API Docs.

The Amazon API creates parsing jobs, reports live progress and returns export files for ecommerce research and catalog workflows.

Preview 5 rows free See 100-row proof run View sample data

Output previewCanonical ProductRow · 10 fields shown

ProductAvailabilityPrice

La Roche-Posay Cicaplast Balm B5 CreamB0060OUV5Y · 4.7 · 20,743 reviews

In stock$18.99

Maybelline Sky High MascaraB08H3JPH74 · 4.5 · 181,639 reviews

In stock$10.82

Aquaphor Healing OintmentB0107QPFBU · 4.8 · 138,730 reviews

In stock$12.79

Dove Sensitive Skin Body WashB00SK71SAG · 4.8 · 62,276 reviews

In stock$10.97

{
  "schema_version": "1.0",
  "status": "succeeded",
  "outcome": "full",
  "has_failures": false,
  "marketplace": "amazon",
  "input_type": "product_url_list",
  "mode": "full_product",
  "delivered_records": 1,
  "records_delivered": 1,
  "records_failed": 0,
  "charged_units": 5,
  "sample": {
    "asin": "B0060OUV5Y",
    "title": "La Roche-Posay Cicaplast Balm B5 Cream",
    "brand": "La Roche-Posay",
    "price": 18.99,
    "currency": "USD",
    "stock_status": "in_stock",
    "stock_text": "In Stock",
    "product_url": "https://www.amazon.com/dp/B0060OUV5Y",
    "rating": 4.7,
    "reviews_count": 20743
  },
  "exports": {
    "jsonl": "/api/v1/jobs/{job_id}/download/jsonl",
    "csv": "/api/v1/jobs/{job_id}/download/csv",
    "xlsx": "/api/v1/jobs/{job_id}/download/xlsx",
    "md": "/api/v1/jobs/{job_id}/download/md"
  }
}

# Amazon product sample

| ASIN | Product | Price (USD) |
| --- | --- | --- |
| B0060OUV5Y | La Roche-Posay Cicaplast Balm B5 Cream | 18.99 |

Illustrative row. Run a live preview for current data.

curl -X POST https://parseshelf.com/api/v1/jobs \
  -H 'Authorization: Bearer $PARSESHELF_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"marketplace":"amazon","input_type":"product_url_list","input_value":"https://www.amazon.com/dp/B0060OUV5Y","mode":"full_product","target_count":20}'

Operational contract

Know what the API will do next.

Build the integration around explicit states instead of treating a successful HTTP response as complete data.

Lifecycle

POST /api/v1/jobs returns a job ID and reservation. Poll GET /api/v1/jobs/{id} until the status is succeeded, failed or cancelled; inspect delivered and failed records before downloading.

Partial rows

A job can deliver listing-level fallback rows when a richer product page did not render. Use the quality summary to decide whether the output is sufficient; if you need richer fields, rerun the selected ASINs in full_product mode.

Errors and limits

Handle 400 validation, 401/403 authentication or access, 404 missing jobs/exports, 429 capacity limits and 5xx provider failures. Use the response message as operator context and retry only transient capacity/provider failures.

Retries and duplicates

The public job-create request accepts an optional Idempotency-Key. Reusing the same key with the same request returns the original job without reserving units twice; reusing it for different input returns 409. Persist the returned job ID alongside your request key.

What v1 does not hide

The public v1 contract is polling-based and does not claim webhook delivery. Use the paginated /api/v1/jobs/{job_id}/rows endpoint when you need canonical records before downloading; store the job ID, source URL, mode and run date for reconciliation.

Procurement-ready

Give security and operations one clear packet.

Start with the public contract; request organization-specific documents when a pilot is approved.

Security surface

API keys are shown once, stored hashed, scoped to the owning workspace and revocable. Keep them in a secret manager and never in a browser URL.

Review acceptable use →

Data and quality

The v1 row contract names asin, product_url, stock_status and stock_text; delivered, failed and partial rows remain visible in job metadata and exports.

Inspect the proof run →

Commercial handoff

Compare the free sample, reviewed sample, pilot and self-serve plans only after confirming your input and field coverage.

Compare plans →

Request the packet

For a procurement review, include your marketplace, expected rows, cadence, retention needs and required export fields.

Request procurement packet

See the workflow

Real screens from the product.

Open a screenshot to inspect the actual path from input to output and observed intelligence.

Current ParseShelf preview interface showing input → live rows — **Input → live rows**A visitor can test one URL or up to 20 ASINs before signing in.

Current ParseShelf output interface showing rows → exports — **Rows → exports**Inspect the columns before choosing your export.

Current ParseShelf research interface showing market intelligence — **Market Intelligence**Compare observed prices and spot changes over time.

Guide

How to use this ParseShelf resource.

Create a job

Send a POST request to /api/v1/jobs with marketplace set to amazon. Choose input_type based on the source: search_url for Amazon search pages, category_url for category pages, product_url_list for direct product URLs, or asin_list for bulk ASIN enrichment.

Use listing_only when you need discovery rows and ranking positions. Use full_product when you need product page fields such as brand, bullets, images, product details, stock text, shipping information, variants and review signals.

Poll progress

The job status endpoint exposes status, delivered record counts, charged units, speed and export readiness. This lets a script wait for completion without guessing when Amazon data is ready.

The dashboard shows the same lifecycle for non-technical users. That makes ParseShelf easier to roll out because product researchers and developers do not need separate tools.

Download exports

Use the download endpoint when status is succeeded. JSONL is line-oriented for pipelines, CSV is portable for BI tools, XLSX is easiest for spreadsheet users and Markdown helps produce quick internal reports.

All export formats come from the same normalized rows, so a team can inspect a spreadsheet and ship a JSONL pipeline without reconciling two schemas.

Recurring exports

Use POST /api/v1/schedules when the same Amazon input should be refreshed on a predictable interval. The minimum interval is 60 minutes and the maximum is 30 days; each due run becomes a normal job with its own status, units, quality receipt and downloadable exports.

Schedules do not hide delivery behind a webhook. Poll or store the returned job ID, use Idempotency-Key when retrying job creation, and pause or delete a schedule through the matching schedule endpoint.

Production checklist

Start with one small input and compare the delivered fields with the report, catalog or pipeline you actually need.

Keep the job ID, source URL, mode and run date with downstream exports so operators and developers can audit the same result.

OpenAPI excerptReference

openapi: 3.1.0
info:
  title: ParseShelf Amazon API
  version: 1.0.0
paths:
  /api/v1/jobs:
    post:
      summary: Create an Amazon parsing job
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          schema: {type: string, maxLength: 255}
  /api/v1/schedules:
    get:
      summary: List recurring Amazon export schedules
    post:
      summary: Create a recurring Amazon export schedule
      description: The first run is queued by the worker at the next interval. Minimum interval is 60 minutes; each run becomes a normal job that can be polled and downloaded.
  /api/v1/schedules/{schedule_id}:
    delete:
      summary: Delete a recurring export schedule
  /api/v1/schedules/{schedule_id}/pause:
    post:
      summary: Pause a recurring export schedule
  /api/v1/schedules/{schedule_id}/resume:
    post:
      summary: Resume a recurring export schedule
  /api/v1/alerts:
    get:
      summary: List Amazon intelligence alerts
    post:
      summary: Create an Amazon intelligence alert
  /api/v1/alerts/{alert_id}/events:
    get:
      summary: Read triggered alert events
  /api/v1/jobs/{job_id}:
    get:
      summary: Read job status and delivered record counts
  /api/v1/jobs/{job_id}/rows:
    get:
      summary: Read paginated canonical ProductRow records
  /api/v1/jobs/{job_id}/repair:
    post:
      summary: Queue repair for incomplete product rows
  /api/v1/jobs/{job_id}/download/{format}:
    get:
      summary: Download jsonl, csv, xlsx or md exports
components:
  schemas:
    ProductRow:
      required: [asin, product_url, stock_status, stock_text]
      properties:
        asin: {type: string}
        product_url: {type: string, format: uri}
        stock_status: {type: string, enum: [in_stock, out_of_stock, limited, delivery_restricted, unknown]}
        stock_text: {type: string}

OpenAPI JSON Python quickstart GitHub Python repo JavaScript quickstart

Pick one Amazon input source: search URL, category URL, product URL list or ASIN list.
Use listing_only for broad discovery and full_product for richer product-page fields.
Keep canonical asin, source_url, product_url, stock_status and stock_text in downstream datasets; map legacy product_id at ingestion.
Download JSONL for pipelines, CSV for imports, XLSX for operators and Markdown for reports.
Record job IDs so dashboard rows and API exports can be reconciled later.
Link related docs, samples and comparison pages when evaluating an Amazon data workflow.

Continue the Amazon data workflow.

FAQ

Amazon Scraper API Docs questions.

What endpoint creates Amazon jobs?

POST /api/v1/jobs creates Amazon parsing jobs from URLs, keywords or ASIN lists.

Can I download CSV through the API?

Yes. Use the job download endpoint with format csv after the job succeeds.

Can I repair incomplete product rows?

Yes. POST /api/v1/jobs/{job_id}/repair queues an additive retry for listing-fallback rows from a completed full_product job.

What mode should I use first?

Use listing_only for discovery and full_product for product details and richer exports.

Can I watch a product over time?

Yes. Create an API-backed alert for price, search position or visible bought floor, then read deduplicated events from /api/v1/alerts/{alert_id}/events.

Do alerts send email or webhooks?

The current alert contract exposes auditable in-app/API events. It does not claim transactional email or webhook delivery.