Getting started

Quickstart

Go from a raw catalog to a live, agent-readable feed in four steps.

Get an API key

Create an account, then generate a key in Dashboard → Settings → API keys. Keys look like sr_ followed by 64 hex characters, carry read and/or write scopes, and are shown once at creation — store yours immediately.

.env

SHELFREADY_API_KEY=sr_9f2c…  # 64 hex chars, shown once at creation

Treat keys like passwords. Never commit them or expose them in client-side code.

1. Connect a source

Connect your store in Dashboard → Sources: WooCommerce, BigCommerce, Magento, an existing feed URL (Google Shopping XML or CSV), or a CSV/XLSX upload. See connecting a store for platform-specific steps.

No supported platform? Push your catalog directly through the API instead — items are validated and upserted in one call:

push-catalog.sh

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: a freestanding two-person shelter for three-season trips.",
      "brand": "Alpine Outdoor",
      "url": "https://yourstore.com/products/ridgeline-2p",
      "imageUrl": "https://yourstore.com/images/ridgeline-2p.jpg",
      "priceMinor": 29900,
      "currency": "EUR",
      "availability": "in_stock",
      "gtin": "4006381333931"
    }]
  }'

2. Run an audit

Audits run automatically after every sync, but you can trigger one on demand. The response is synchronous — you get the catalog score and grade right away.

audit.sh

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

response.json

{
  "data": {
    "run_id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0",
    "catalog_score": 72,
    "grade": "B"
  }
}

3. Get your feed URLs

Feeds re-render automatically after every sync. List the hosted, tokenized URLs for all four surfaces — ACP CSV, ACP JSON, Google Merchant Center TSV, and schema.org JSON-LD:

feeds.sh

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

Feeds inherit the readiness of your catalog. Fix error-severity findings first — they mark spec violations that make items ineligible on the target surface.

4. Verify the output

Each feed lives at a stable URL of the form https://useshelfready.com/f/<your-slug>/<token>/acp.json. Fetch it to confirm items render, then hand the URL to your agent integration.

bash

curl "https://useshelfready.com/f/<your-slug>/<token>/acp.json"

That is the full loop. Next, read core concepts to understand how scoring and rules work under the hood.