Skip to main content

Developers

Merchant API

A read-only REST API for your VeeBoost store: one published contract, key-based authentication and predictable pagination — built for integrations that stay in sync.

One contract, published as the single source of truth

Your store publishes the complete machine-readable contract (OpenAPI 3.1): every endpoint, parameter, response and error code of the merchant API. This page links to it and never restates endpoint tables — the contract cannot drift, and neither can your integration.

Published contractGET /openapi/v1.json

Quickstart

Three steps to your first catalog read:

  1. Create an API key in your admin (Developers section) with the read scopes you need. It starts with vbk_ and is displayed only once.
  2. Send it in the X-Api-Key header on every request — your tenant is resolved from the key, never from the host.
  3. Call your first endpoint, for example GET /products, then follow the contract for everything else.

Authentication

Every request carries your key in the X-Api-Key header. v1 ships exactly four read scopes — products, orders, customers and webhook deliveries. A missing scope answers 403, a revoked key is refused immediately. Keep keys server-side: they never belong in a browser or a public repository.

products:readorders:readcustomers:readwebhooks:read

Pagination

List endpoints paginate: walk them with the page parameter and read the envelope returned with every collection — it reports where you are so your integration can resync without guessing. The exact parameters of each endpoint are documented in the contract.

Errors and rate limits

Errors return a structured JSON body you can parse, never a paragraph to screen-scrape. A 429 response is a stable contract: the same body shape every time, with the X-RateLimit-* headers and a Retry-After that says exactly when to come back. Bursting does not unlock data — back off.

Sandbox keys

During the pre-launch gate, sandbox keys are issued after validation by our team and run with a dedicated rate-limit budget, separate from production keys — explore the API against your store without touching live traffic or quotas.

Examples by language

One snippet per platform, read scopes only: each pulls your product catalog. Replace <api-base> with your store API host shown in the admin → Developers section.

curl

curl -H "X-Api-Key: vbk_your_key" \
  "https://<api-base>/products?page=1"

JavaScript

async function listProducts(page = 1) {
  const res = await fetch("https://<api-base>/products?page=" + page, {
    headers: { "X-Api-Key": "vbk_your_key" },
  });
  if (res.status === 429) {
    // Structured contract: honor Retry-After, never screen-scrape.
    const wait = Number(res.headers.get("Retry-After")) * 1000;
    await new Promise((done) => setTimeout(done, wait));
    return listProducts(page);
  }
  if (!res.ok) throw new Error("products:read failed with " + res.status);
  return res.json();
}

Python

import requests

def list_products(page=1):
    res = requests.get(
        "https://<api-base>/products",
        params={"page": page},
        headers={"X-Api-Key": "vbk_your_key"},
        timeout=10,
    )
    res.raise_for_status()
    return res.json()

v1 is read-only by design: products:read, orders:read, customers:read and webhooks:read are the only scopes that exist. Write scopes would be an explicitly documented v1.x decision — none is planned silently.