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.
GET /openapi/v1.jsonQuickstart
Three steps to your first catalog read:
- Create an API key in your admin (Developers section) with the read scopes you need. It starts with vbk_ and is displayed only once.
- Send it in the X-Api-Key header on every request — your tenant is resolved from the key, never from the host.
- 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:readPagination
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.