API reference

Products

Read your ingested canonical catalog. Products are read-only through this API; they change via syncs, catalog pushes, and approved enrichment.

List products

GET/api/v1/products

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

Parameter	Type	Description
`page`	integer	Page number, starting at 1. Defaults to 1.
`page_size`	integer	Page size, 1–100. Defaults to 50.

bash

curl "https://useshelfready.com/api/v1/products?page=1&page_size=2" \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"

response.json

{
  "data": [
    {
      "id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0",
      "externalId": "SKU-1",
      "title": "Ridgeline 2P Tent",
      "description": "Storm-tested and light…",
      "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",
      "mpn": null,
      "variants": []
    }
  ],
  "page": 1,
  "page_size": 2,
  "total": 1284
}

Retrieve a product

GET/api/v1/products/{id}

One product with its variants, by its ShelfReady UUID. Requires the read scope. Returns 404 if the product does not exist in your workspace.

bash

curl https://useshelfready.com/api/v1/products/0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0 \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"

The product object

Parameter	Type	Description
`id`	uuid	Unique ShelfReady product identifier.
`externalId`	string	Your stable ID for the product (SKU).
`title`	string	Product title (150-character ACP cap).
`description`	string \| null	Plain-text description.
`brand`	string \| null	Brand name.
`url`	string \| null	HTTPS product page URL.
`imageUrl`	string \| null	HTTPS primary image URL.
`priceMinor`	integer \| null	Price in integer minor units (2450 = €24.50).
`currency`	string \| null	ISO-4217 currency code.
`availability`	string	ACP enum: in_stock, out_of_stock, pre_order, backorder, unknown.
`gtin`	string \| null	Global trade item number, if present.
`mpn`	string \| null	Manufacturer part number, if present.
`variants`	object[]	Variant rows (externalId, sku, priceMinor, currency, availability, gtin, mpn, color, size).