Skip to content

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.

  1. Go to Settings › API Keys and click Create API Key.
  2. Give the key the read:products scope. It is the only scope this guide needs.
  3. 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.

Terminal window
export ECOMWEB_API_KEY=<secret key>
export ECOMWEB_STORE_REF=<store ref>

Send the key in the x-api-key header. The base URL is https://apibase.ecomweb.app/api/v1.

Terminal window
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.

Node.js 24 has fetch, so you need no package. Save this as products.mjs. It reads every page by following meta.hasNext.

products.mjs
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);
}
Terminal window
node products.mjs

Lists 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.

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.