Shoppage Search API

Query every Shoppage surface from your own software: the same results as the site, as JSON.

Get a key

Create an API key from your account. Keys look like sp_live_… and are shown once. Keep them secret; revoke a key from the same page if it leaks.

Search

GET /api/v1/search?q=stoneware+mug&surface=shopping&page=1&limit=20
Authorization: Bearer sp_live_YOUR_KEY

Parameter	Description
`q`	Search text (up to 300 characters). Required by most surfaces.
`surface`	One of `all`, `shopping`, `maps`, `videos`, `images`, `news`. Defaults to `all`.
`page`	Page number, from 1.
`limit`	Results per page, up to 50.
`f.<field>`, `sort`	The same filters and sort orders as the website's search pages (for example `f.shop=studio-clay`, `sort=price_asc`).

You can pass the key as ?key= for quick tests, but prefer the Authorization header so keys don't end up in logs and browser history.

Response

{
  "query": "stoneware mug",
  "surface": "shopping",
  "total": 42,
  "page": 1,
  "page_size": 20,
  "results": [
    {
      "title": "Speckled stoneware mug",
      "url": "https://…/shop/studio-clay/product/1",
      "snippet": "A 350 ml mug with a speckled oatmeal glaze.",
      "image": "https://…",
      "source": "Studio Clay",
      "meta": { "price": 28, "currency": "USD", "shop": "studio-clay", "availability": "In stock" }
    }
  ]
}

Catalogue (for shops)

A shop owner's key also manages that shop's products, so a POS, ERP or stock system can keep prices and stock current. Products are addressed by SKU.

Call	Does
`GET /api/v1/products?page=&limit=`	Lists your products (up to 200 a page).
`GET /api/v1/products/{sku}`	One product.
`PUT /api/v1/products/{sku}`	Creates or replaces a product. Needs at least `title` and `price`. Answers 201 when created.
`PATCH /api/v1/products/{sku}`	Changes only the fields you send, e.g. `{"price": 4499, "stock": 3}`.
`DELETE /api/v1/products/{sku}`	Archives the product (it becomes a draft).

curl -X PATCH /api/v1/products/GEN-3K   -H "Authorization: Bearer sp_live_…" -H "Content-Type: application/json"   -d '{"price": 4499, "stock": 3}'

Fields: title, description, price, compare_at_price, currency, stock, status (active/draft), images, brand, category, barcode, tags, weight_kg. Unknown fields are refused. Errors: invalid (422), sku_taken and catalogue_limit (409), no_shop (403, the key's owner has no shop). Prefer a spreadsheet? Use Product feeds in the dashboard.

Limits

Each key has a daily quota that you set (up to the platform maximum), counted per UTC day, and a short-term rate limit of a few requests per second.

Errors

Errors are JSON: {"error": {"code": "…", "message": "…"}}.

Status	Code	Meaning
400	`unknown_surface`, `query_too_long`	Fix the request.
401	`unauthorized`	Missing, wrong or revoked key.
429	`quota_exceeded`	Daily quota used; `Retry-After` says when it resets.
429	`rate_limited`	Too fast; wait for `Retry-After` seconds.
500	`internal`	Our fault; retry later.