Developer docs

ParseShelf Amazon API Documentation.

Use these docs to create Amazon jobs, choose the right input type, poll progress and download structured exports from ParseShelf.

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.

Core job model

A ParseShelf job starts with a marketplace, input type, input value, mode and target count. The same contract works for Amazon search URLs, category URLs, product URLs and ASIN lists, so a developer can switch sources without rewriting downstream export logic.

The dashboard and API share the same job lifecycle. Operators can create and inspect jobs in the web product while engineers automate recurring runs with API keys.

Output contract

The v1 contract uses asin, product_url, stock_status and stock_text as canonical Amazon fields, plus title, brand, price, currency, rating, reviews_count, category_path and images. Existing exports may include product_id as a deprecated compatibility alias for asin; new integrations should use asin.

Each export format is generated from the same normalized rows. JSONL is best for pipelines, CSV and XLSX are best for analysts, and Markdown is useful for internal reports.

Rows and repair

Use the rows endpoint when a client needs paginated canonical records before downloading a file. It accepts search, sort, quality and page parameters and returns the same ProductRow shape as the exports.

If a completed full_product job contains listing-fallback rows, POST to the repair endpoint to queue an additive retry. The repair response has its own state and reservation; clients should poll the parent job and keep the original row quality visible.

Next steps

Start with the API overview if you need the complete endpoint map. Use the Python or JavaScript quickstart when you are wiring ParseShelf into a backend. Use the Google Sheets and Postman guides when the first user is an operator or analyst.

For SEO and research workflows, pair these docs with the public sample dataset and benchmark page so buyers can evaluate the data shape before signing up.

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.

API mapReference

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

ParseShelf Amazon API Documentation questions.

Where are the API examples?

The docs hub links to Python, JavaScript, Google Sheets and Postman examples for Amazon product data jobs.

Which exports are supported?

Completed Amazon jobs can export JSONL, CSV, XLSX and Markdown.

Is this only for developers?

No. The same jobs can be created from the dashboard, then automated later through API keys.