ShelfReady / docs

API reference

Everything the dashboard does, as a REST API: push your catalog, trigger syncs, read your hosted feed URLs and agent-readiness audit results. Machine-readable spec at /api/v1/openapi.json.

Authentication

Create an API key in Dashboard → Settings → API keys. Keys look like sr_…, are shown once at creation, and carry read and/or write scopes. Send the key on every request:

curl https://useshelfready.com/api/v1/products \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"

Errors & rate limits

Errors share one shape. Keys are limited to 60 requests/minute; a 429 includes a Retry-After header.

{"error": {"status": 403, "message": "this key lacks the \"write\" scope"}}
get/api/v1/productsscope: read

List products

The canonical catalog with variants, paginated. Requires the read scope.

curl https://useshelfready.com/api/v1/products \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"
get/api/v1/products/{id}scope: read

Get one product

One product with its variants. Requires the read scope.

curl https://useshelfready.com/api/v1/products/<uuid> \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"
post/api/v1/catalogscope: write

Push catalog items

Push canonical-shaped items through the sync pipeline (validation → upsert). Items land on an auto-provisioned api source; rejected items are reported per-item and never touch the catalog. Requires the write scope.

curl -X POST https://useshelfready.com/api/v1/catalog \
  -H "Authorization: Bearer $SHELFREADY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "externalId": "SKU-1",
      "title": "Ridgeline 2P Tent",
      "description": "Storm-tested and light.",
      "url": "https://yourstore.com/tent",
      "imageUrl": "https://yourstore.com/tent.jpg",
      "priceMinor": 29900,
      "currency": "EUR",
      "availability": "in_stock",
      "gtin": "4006381333931"
    }]
  }'
get/api/v1/syncsscope: read

List sync runs

The 50 most recent sync runs, newest first. Requires the read scope.

curl https://useshelfready.com/api/v1/syncs \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"
post/api/v1/syncsscope: write

Trigger a sync

Run a pull sync for one source (WooCommerce, BigCommerce, Magento, feed URL) now. Requires the write scope.

curl -X POST https://useshelfready.com/api/v1/syncs \
  -H "Authorization: Bearer $SHELFREADY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_id": "<uuid>"}'
get/api/v1/feedsscope: read

List hosted feed URLs

Tokenized URLs for every feed surface (ACP CSV/JSON, Google Merchant Center TSV, JSON-LD) plus the last render run. Requires the read scope.

curl https://useshelfready.com/api/v1/feeds \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"
post/api/v1/feedsscope: write

Re-render feeds

Regenerate all feed artifacts now. Requires the write scope.

curl -X POST https://useshelfready.com/api/v1/feeds \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"
get/api/v1/auditscope: read

Get audit results

The latest audit run and the current findings snapshot. Requires the read scope.

curl https://useshelfready.com/api/v1/audit \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"
post/api/v1/audit/runsscope: write

Run the audit

Score the catalog for agent readiness now. Requires the write scope.

curl -X POST https://useshelfready.com/api/v1/audit/runs \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"
get/api/v1/webhooksscope: read

List webhooks

Registered webhook endpoints (signing secrets are never returned). Requires the read scope.

curl https://useshelfready.com/api/v1/webhooks \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"
post/api/v1/webhooksscope: write

Register a webhook

Register an HTTPS endpoint for event deliveries. The response includes the signing secret **once** — verify each delivery's X-ShelfReady-Signature (t=<unix ts>,v1=<hex HMAC-SHA256 of "<ts>.<body>">). Failed deliveries retry after 1m/5m/30m/2h/12h, then stop. Requires the write scope.

curl -X POST https://useshelfready.com/api/v1/webhooks \
  -H "Authorization: Bearer $SHELFREADY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/shelfready",
    "events": ["sync.completed", "audit.completed"]
  }'
delete/api/v1/webhooksscope: write

Delete a webhook

Remove a webhook endpoint. Requires the write scope.

curl -X DELETE https://useshelfready.com/api/v1/webhooks \
  -H "Authorization: Bearer $SHELFREADY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "<uuid>"}'