API reference

Catalog

Push products straight from your own systems — the API-push alternative to connecting a store.

Push catalog items

POST/api/v1/catalog

Push 1–5000 canonical-shaped items through the sync pipeline (validation → upsert). Items land on an auto-provisioned api source; the response is a sync run with per-item stats. Requires the write scope.

push.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"
    }]
  }'

response.json

{
  "data": {
    "run_id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0",
    "source_id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
    "stats": { "seen": 1, "upserted": 1, "rejected": 0, "warnings": 0, "rejections": [] }
  }
}

The catalog item

Only externalId and title are required to upsert, but every field below feeds eligibility on the AI-surface feeds — the audit tells you what is missing.

Parameter	Type	Description
`externalId`req	string	Stable ID in your system (SKU). Upserts match on it.
`title`req	string	Product title, at most 150 characters (ACP cap).
`description`	string	Plain text (no HTML), at most 5000 characters.
`brand`	string	Brand name.
`url`	string	HTTPS product page URL.
`imageUrl`	string	HTTPS primary image URL.
`priceMinor`	integer	Price in integer minor units — 2450 for €24.50.
`currency`	string	ISO-4217 code, e.g. EUR.
`availability`	string	One of in_stock, out_of_stock, pre_order, backorder, unknown. Defaults to unknown.
`gtin`	string	GTIN — validated against length and GS1 checksum.
`mpn`	string	Manufacturer part number.
`variants`	object[]	Variant objects (externalId, sku, priceMinor, currency, availability, gtin, mpn, color, size).

Validation & rejections

Every item is validated against the canonical model. Items that fail (invalid GTIN checksum, non-HTTPS URL, unknown currency, overlong title) are rejected per-item and reported in stats.rejections with field-level issues — they never touch your catalog. Valid items in the same request are upserted normally.

A successful push cascades like any sync: feeds re-render, the audit re-runs, and a sync.completed webhook is emitted.