Quickstart: Store API
You send your first Store API request and read a list of products. The Store API is for servers, scripts and CI that work with one store’s data using a secret key. You need the store owner to create the key. Later steps use curl and Node.js 24.
Create a secret key
Section titled “Create a secret key”- Go to Settings › API Keys and click Create API Key.
- Give the key the
read:productsscope. It is the only scope this guide needs. - Copy the key when it is shown. You cannot see it again.
For every field and what a key can reach, see Create and manage API keys and Scopes. Keep the key on a server. Never put it in code that runs in the browser.
Export it, and your store’s reference, so the examples can use them. If you use the CLI, ecomweb auth status prints it as store_ref.
export ECOMWEB_API_KEY=<secret key>export ECOMWEB_STORE_REF=<store ref>Make your first request
Section titled “Make your first request”Send the key in the x-api-key header. The base URL is https://apibase.ecomweb.app/api/v1.
curl "https://apibase.ecomweb.app/api/v1/stores/$ECOMWEB_STORE_REF/products?limit=2" \ -H "x-api-key: $ECOMWEB_API_KEY"The response has the products in data and the paging state in meta:
{ "data": [ { "id": 101, "name": "Linen shirt", "slug": "linen-shirt" }, { "id": 102, "name": "Canvas tote", "slug": "canvas-tote" } ], "meta": { "total": 134, "limit": 2, "offset": 0, "page": 1, "totalPages": 67, "hasNext": true, "hasPrev": false }}Each product carries more fields than the example shows. The Store API reference lists them.
Call it from Node
Section titled “Call it from Node”Node.js 24 has fetch, so you need no package. Save this as products.mjs. It reads every page by following meta.hasNext.
const base = "https://apibase.ecomweb.app/api/v1";const storeRef = process.env.ECOMWEB_STORE_REF;const apiKey = process.env.ECOMWEB_API_KEY;
async function* listProducts() { const limit = 100; let offset = 0; while (true) { const res = await fetch(`${base}/stores/${storeRef}/products?limit=${limit}&offset=${offset}`, { headers: { "x-api-key": apiKey }, }); if (!res.ok) { const error = await res.json().catch(() => ({})); throw new Error(`HTTP ${res.status}: ${error.message ?? res.statusText}`); } const { data, meta } = await res.json(); yield* data; if (!meta.hasNext) return; offset += limit; }}
for await (const product of listProducts()) { console.log(product.id, product.name);}node products.mjsLists use limit and offset, not a cursor. For sorting, date filters and a note on items that change while you read, see Rate limits and pagination.
Handle errors
Section titled “Handle errors”When a request fails the API answers 4xx or 5xx with a JSON body. The body has one of three shapes, so check the status first. A wrong key, for example, gives this:
{ "message": "Invalid API key", "error": "Unauthorized", "statusCode": 401 }A key without the read:products scope gets a 403. A 429 means slow down, and the errors guide says which failures are safe to retry. The script above throws with the status and message, which is enough to tell a bad key from a missing scope.
Next steps
Section titled “Next steps”- Every Store API operation: Store API reference
- Which scope each operation needs: Scopes
- Keys, headers and refusals: Authentication