ShelfAtlas Catalog API

The ShelfAtlas Catalog API provides read access to normalised Danish retail catalog data — products, offers, stores, and chains — via a simple REST interface.

Data coverage: the offer feed covers every major Danish chain, but the curated product catalog is smaller and actively expanding. Offers only appear under a product (and in price history) once they have been matched to a curated product — an empty data array from those endpoints means "no offers linked yet", not an error. Compare productsCount with liveOffers in the unauthenticated GET /api/v1/public/catalog/stats endpoint for the live numbers.

Authentication

All requests require a valid API key in the Authorization header:

Authorization: Bearer sa_live_<your-key>

Generate a key at app.shelfatlas.com. New keys start on the Free plan — 1,000 requests per calendar month, at no cost. Paid plans raise both the monthly quota and the per-minute rate limit; see pricing. Requests beyond either limit return 429.

Looking for a reference an AI agent can consume directly? See /docs/llms.txt — machine-readable reference for AI agents. The full OpenAPI 3.1 spec describes every endpoint, parameter, and response schema — and is the contract our official SDKs conform to.

Endpoints

Base URL: https://api.shelfatlas.com

GET /api/v1/public/catalog/products — scope filters

Four optional query parameters narrow the product list. Each of brand_id, category_id, and ids is a comma-separated list of UUIDs (max 100 entries each). A product matches if it hits any of the values across those three lists (they OR together — category_id matches on the product's primary category). exclude_ids (same CSV/100 format) always wins — a product listed there is removed even if it matched an include list.

curl "https://api.shelfatlas.com/api/v1/public/catalog/products?brand_id=<uuid>&exclude_ids=<uuid>" \
  -H "Authorization: Bearer sa_live_<your-key>"

GET /api/v1/public/catalog/offers — product_ids

product_ids is a comma-separated list of up to 100 UUIDs. Returns offers matched (via offer_product_matches) to any of the listed products, cursor-paginated like the rest of this endpoint. product_ids cannot be combined with product_id (the single-product form) or chain_slug — doing so returns 400 incompatible_params.

curl "https://api.shelfatlas.com/api/v1/public/catalog/offers?product_ids=<uuid>,<uuid>" \
  -H "Authorization: Bearer sa_live_<your-key>"

GET /api/v1/public/catalog/price-history

Per-day minimum price (in øre, across all chains) for a set of products, over a trailing window. Backed by the same reader used for skin price-history charts — catalog offers and price observations are unioned, so the series reflects both sources.

curl "https://api.shelfatlas.com/api/v1/public/catalog/price-history?product_ids=<uuid>&days=7" \
  -H "Authorization: Bearer sa_live_<your-key>"

{
  "ok": true,
  "data": [
    { "productId": "<uuid>", "date": "2026-07-01", "minPriceCents": 1295, "chainSlug": "netto" }
  ]
}

No pagination — the response covers every day in range for every requested product.

GET /api/v1/public/catalog/stores — geo search

Returns the formal store payload: id, name, chainSlug, chainName, address, city, postalCode, lat, lng, openingHours, timezone.

curl "https://api.shelfatlas.com/api/v1/public/catalog/stores?lat=55.6761&lng=12.5683&radius_km=5" \
  -H "Authorization: Bearer sa_live_<your-key>"

{
  "ok": true,
  "data": [
    {
      "id": "...", "name": "Netto Østerbro", "chainSlug": "netto", "chainName": "Netto",
      "address": "Østerbrogade 1", "city": "København", "postalCode": "2100",
      "lat": 55.7, "lng": 12.58, "openingHours": null, "timezone": "Europe/Copenhagen"
    }
  ],
  "pagination": { "limit": 50, "cursor": null }
}

No cursor pagination on this endpoint — results are either the whole (small) chain list or distance-ordered geo results, and pagination.cursor is always null. An unknown chain_slug narrows to an empty list rather than 404ing, matching how chain_slug filters behave on the other list endpoints.

Pagination

List endpoints support ?limit= (default 50, max 200) and ?cursor= for cursor-based pagination. The response includes pagination.cursor for the next page, or null when no more results.

GET /api/v1/public/catalog/offers?chain_slug=rema&limit=10

{
  "ok": true,
  "data": [...],
  "pagination": { "limit": 10, "cursor": "uuid-of-last-row" }
}

Example

curl https://api.shelfatlas.com/api/v1/public/catalog/chains \
  -H "Authorization: Bearer sa_live_<your-key>"

Rate limits and quotas

Two independent limits apply per API key, both driven by the key owner's plan — per calendar month (UTC), not lifetime:

Partner (internal skin) keys are not plan-gated: a fixed, generous per-minute budget and no monthly quota. Exceeding the per-minute rate returns 429 rate_limited with a Retry-After header (seconds). Exceeding the monthly request quota returns 429 monthly_limit_reached with the caller's plan, limit, and an upgrade_url in the response body. Upgrade your plan or see the full pricing table.

The Free and Hobby plans are for personal, non-commercial use. If a company is behind the traffic, or the data goes into a product or service you sell, you need the Standard plan or higher. The commercial plans are what buy you notice before this API changes — on the personal plans we may change or rate-limit it at short notice. See the terms.

Every authenticated response tells you where you stand — you never have to wait for the wall to find out. Self-serve keys get three headers on every response, success or error: X-Quota-Limit (your plan's monthly request quota), X-Quota-Remaining (requests left this month, after the one you just made), and X-Quota-Reset (ISO-8601 instant when the quota resets — the start of the next UTC month). Partner keys carry no monthly quota and therefore no quota headers.

We also email the key owner once at 80% of the monthly quota and once when it is reached, at the address on their ShelfAtlas account.

Error codes

Data accuracy & ownership

Catalog data is extracted from publicly published retailer leaflets and provided as-is, without warranty. Product names, logos, trademarks and leaflet imagery belong to their respective owners; the structured catalog is the work of ShelfAtlas. Prices and validity periods may contain errors — the retailer's own printed leaflet always prevails. Verify price-critical decisions against the retailer's published material.

Shelf observations (write)

POST /api/v1/observations records a crowd-sourced shelf signal — stock status, and optionally a price — for a product or offer at a store.

Who can write

Any API key — free or partner tier — can submit an observation with the usual Authorization: Bearer sa_live_<your-key> header. Callers without a key can submit anonymously with an X-Device-Token header: a UUID you generate and keep client-side to represent this device — any UUID version is accepted, the check is purely the 8-4-4-4-12 hex-digit shape. Sending both an Authorization header and an X-Device-Token header uses the API key. Contributing observations earns no reward and no extra requests — it is not coupled to your quota in either direction, beyond the normal write-endpoint rate limit below.

Request body

Exactly one of ean or offer_id is required — the other is omitted.

curl -X POST https://api.shelfatlas.com/api/v1/observations \
  -H "Authorization: Bearer sa_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "3f2a9c10-2b34-4e2a-9c3e-1a2b3c4d5e6f",
    "ean": "5701234567890",
    "stock_status": "out_of_stock"
  }'

Response

201on success, with the observation's id and moderation outcome:

{
  "id": "<uuid>",
  "moderation_status": "approved" | "pending_review"
}

An observation auto-approves (moderation_status: "approved") when it comes from a trusted source: any request authenticated with a partner-tier API key, or any caller whose device already has 5 or more approved observations. Everything else starts as pending_review. A submitted price that is a large outlier against the product's known catalog prices is always held for review, even from a trusted source. Only approved observations feed the stock fields returned by GET /api/v1/public/catalog/stores/:id/stock today.

An API-key request that resolves to an identified reporter — via reporter_clerk_id or the key's own owner — may additionally receive a top_reporter object in the response; treat any field not documented above as optional.

Rate limits

Every request to this endpoint, regardless of how it is authenticated, shares the platform's write-route budget: 10 requests/minute per IP (separate from the read-endpoint numbers in Rate limits and quotas above, which don't apply here). An anonymous X-Device-Token caller additionally gets its own budget of 50 requests per 15 minutes, checked twice — once per IP and once per device token — so a freshly generated device id can't be used to dodge the IP-level limit. Submitting via an API key does notcount against the key's monthly request quota and does not carry the X-Quota-* headers described above — this endpoint is not plan-gated.

Errors

Unlike the rest of the Catalog API (which returns only error), this endpoint's error body carries both error and code — the same value in both fields. See Error codes above for what each HTTP status means; the codes specific to this endpoint are:

MCP Server

ShelfAtlas exposes the same catalog data as an MCP (Model Context Protocol) server, so AI assistants like Claude Desktop, Cline, and Cursor can query Danish retail data directly. One endpoint, stateless JSON transport, same API key.

Endpoint

POST https://api.shelfatlas.com/api/v1/mcp

Authentication is identical to the REST API — pass your key in the Authorization header. Query-string auth is not supported.

curl https://api.shelfatlas.com/api/v1/mcp \
  -H "Authorization: Bearer sa_live_<your-key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tools

Pagination: tools that accept cursor return nextCursor in the response. Pass it as cursor on the next call. Default limit 20, max 50.

Claude Desktop configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "shelfatlas": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.shelfatlas.com/api/v1/mcp"],
      "env": {
        "MCP_REMOTE_HEADER_AUTHORIZATION": "Bearer sa_live_<your-key>"
      }
    }
  }
}

Uses mcp-remote to bridge the HTTP endpoint to Claude Desktop's stdio transport. No local server required.

Claude Code

Claude Code speaks HTTP MCP natively — no bridge process:

claude mcp add --transport http shelfatlas https://api.shelfatlas.com/api/v1/mcp \
  --header "Authorization: Bearer sa_live_<your-key>"

Cursor / Cline / other MCP clients

Any client that supports stdio MCP servers can use the same mcp-remotebridge as Claude Desktop — the JSON block above works unchanged in Cursor's .cursor/mcp.jsonand Cline's MCP settings. Clients that support remote HTTP servers directly can point straight at the endpoint with the same Authorization header.

Try asking

With the server connected, questions like these resolve against live catalog data:

• “Where is Pepsi Max cheapest in Odense right now?”
• “Which chains have it on offer this week, and until when?”
• “Find the nearest REMA 1000 that carries it.”
• “Look up EAN 5741000124123 and show its current offers.”

Webhooks (beta)

A webhook subscription registers an HTTPS endpoint of yours to receive signed POST requests when catalog events happen — so you can react to new offers as they are published, without polling. Create and manage subscriptions at app.shelfatlas.com/app/webhooks.

The payload

When an ingest run creates new offers, we send one POST per subscription carrying every offer that run created (batched — never one request per offer). The body:

{
  "event": "offer.upserted",
  "occurred_at": "2026-07-12T10:00:00.000Z",
  "delivery_id": "0f9c…",           // unique per delivery — use as an idempotency key
  "data": [
    {
      "change": "created",
      "offer": {
        "id": "…", "rawName": "Pepsi Max 24x33cl",
        "price": "99.00", "currency": "DKK",
        "validFrom": "2026-07-01T00:00:00.000Z",
        "validTo": "2026-07-08T00:00:00.000Z",
        "chainId": "…", "storeId": null, "productId": "…",
        "volumeMl": 330, "unitCount": 24, "imageUrl": null,
        "originalPrice": null, "discountPct": null,
        "unitPrice": null, "unitPriceUnit": null
      }
    }
  ]
}

Signing secret & verification

Each subscription has its own signing secret, shown once when you create it (save it — it is not retrievable later). Every delivery carries an X-ShelfAtlas-Signature header — sha256= followed by the HMAC-SHA256 of the raw request body keyed with your secret. Recompute it and compare to confirm the request came from ShelfAtlas:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, headerSig, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(headerSig);
  return a.length === b.length && timingSafeEqual(a, b);
}

Retries & delivery guarantees

Delivery is at-least-once. A delivery is retried on any non-2xx response, timeout, or network error with an escalating backoff (roughly 1m, 5m, 30m, 2h, 6h, 24h) for up to six attempts before it is marked failed. Because a request can be retried, treat delivery_id as an idempotency key and return a 2xx quickly. Deliveries are still in beta — dispatched by a background job that runs every 15 minutes, so expect up to ~15 minutes of latency between an offer appearing and its delivery arriving. See /status for live per-chain catalog freshness and webhook-delivery health.