Veribl for Node.js and TypeScript

The official SDK for the Veribl API: products, digital product passports (EN 18222), battery units, articles, files and webhooks.

npm install veribl

Node 20 or later, Deno, Bun or any runtime with fetch and Web Crypto. No dependencies.

Quickstart

Make an API key in the Veribl dashboard under Settings › API keys. Keys that start with vdpp_test_ reach your test workspace, so you can build without touching live passports.

import Veribl from 'veribl';

const veribl = new Veribl(process.env.VERIBL_API_KEY);

// Create a product
const product = await veribl.products.create({ name: 'E-bike battery pack 36V', gtin: '09506000134352' });

// Read its passport through the Passport API (EN 18222)
const passport = await veribl.dpps.retrieveByProductId('https://go.veribl.com/01/09506000134352');
console.log(passport.dppHeader);

Every request and response is typed from the API's OpenAPI description, so your editor shows each field and its meaning.

Lists

Await a list for one page, or loop over it to walk every item. The SDK fetches the next pages for you.

const page = await veribl.products.list({ status: 'live', limit: 50 });
page.data;        // up to 50 products
page.nextCursor;  // pass as `cursor` for the next page, null on the last

for await (const product of veribl.products.list({ status: 'live' })) {
  console.log(product.name);
}

Errors

Failed calls throw a VeriblError subclass with the HTTP status, a code and the Request-Id. Look up the Request-Id in the dashboard under Developers › Logs to see the full request and response.

import { VeriblInvalidRequestError } from 'veribl';

try {
  await veribl.products.retrieve('prod_missing');
} catch (e) {
  if (e instanceof VeriblInvalidRequestError && e.code === 'not_found') {
    console.log(`Not found (request ${e.requestId})`);
  } else throw e;
}

| Class | When | | --- | --- | | VeriblAuthenticationError | 401: the key is missing, wrong, revoked or expired | | VeriblPermissionError | 403: the key or plan doesn't allow this | | VeriblInvalidRequestError | 400, 404, 409: something about the request | | VeriblRateLimitError | 429: too many requests (after retrying) | | VeriblAPIError | 5xx: a problem on Veribl's side (after retrying) | | VeriblConnectionError | No answer: network or timeout (after retrying) |

Retries and idempotency

Network errors, 429 and 5xx answers are retried twice by default, with backoff and respecting Retry-After. Every write is sent with an Idempotency-Key, the same on each retry, so a retried write is applied only once. You can pass your own key, for example an order number:

await veribl.products.create({ name: 'Bike' }, { idempotencyKey: 'import-2026-10-21-row-17' });

const veribl = new Veribl(key, { maxRetries: 5, timeout: 20_000 });

Webhooks

Check the Veribl-Signature header before trusting a delivery. Pass the body exactly as received, before parsing it.

import express from 'express';
import Veribl from 'veribl';

const app = express();
app.post('/webhooks/veribl', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = await Veribl.webhooks.constructEvent(req.body, req.headers['veribl-signature'] as string, process.env.VERIBL_WEBHOOK_SECRET!);
  } catch {
    return res.sendStatus(400);
  }
  if (event.event === 'passport.published') {
    // event.data.productId …
  }
  res.sendStatus(200);
});

Deliveries are retried for about 3 days, and event.id is the same on every retry, so use it to skip events you have already handled. Signatures older than 5 minutes are rejected; change that with the fourth argument.

API versions

Your key uses the API version that was current when you made it. To try a newer version before switching the key, pin it in the client or on one call:

const veribl = new Veribl(key, { apiVersion: '2026-10-21' });

Any other call

veribl.request(method, path, { query, body }) calls endpoints this SDK version doesn't name yet.

License

MIT