taventifor developers
JS SDK

Build your own ordering

@taventi/sdk is a small typed client for the public API, for browsers and Node. Restaurants' own Taventi sites are built on it. Every answer is checked against Taventi's schemas before you get it.

Setup

Terminal
npm install @taventi/sdk
TypeScript
import { createTaventiClient } from "@taventi/sdk";

const taventi = createTaventiClient({ baseUrl: "https://api.taventi.app" });

// In Next.js server components, skip the fetch cache for live data:
const live = createTaventiClient({
  baseUrl: "https://api.taventi.app",
  requestInit: { cache: "no-store" },
});

Takeaway, step by step

1. The menu

TypeScript
const { location, menu } = await taventi.getLocationMenu("beastie-antwerp");

location.takeaway.enabled; // false: show that online ordering is closed
for (const category of menu.categories) {
  for (const product of category.products) {
    product.name.nl;      // { nl, fr, en }
    product.priceCents;   // 1250 = €12.50, this location's price
    product.available;    // false: sold out
    product.modifierGroupIds; // its option groups (in menu.modifierGroups)
  }
}

2. Price the cart

Keep the cart as product ids, quantities and chosen options. Ask Taventi for the prices whenever it changes, and show those:

TypeScript
const priced = await taventi.priceCart({
  locationId: location.id,
  lines: [{ productId: burger.id, quantity: 2, modifierIds: [extraCheese.id] }],
});
priced.totalCents; // what the guest pays at pickup

3. Pickup time

TypeScript
const pickup = await taventi.getPickupSlots("beastie-antwerp");
pickup.acceptingOrders; // false: takeaway is off or paused right now
pickup.asap.pickupAt;   // "as soon as possible" means this time
pickup.slots.filter((slot) => slot.available); // times the guest can choose

4. Place the order

Make one idempotency key when checkout starts and keep it for every retry of that checkout:

TypeScript
import { newIdempotencyKey, TaventiApiError } from "@taventi/sdk";

const idempotencyKey = newIdempotencyKey(); // once per checkout

try {
  const order = await taventi.createOrder(
    {
      locationId: location.id,
      lines: cart.lines,
      customer: { name: "Lena", phone: "+32 470 12 34 56", email: "lena@example.com" },
      pickup: { type: "asap" }, // or { type: "scheduled", at: slot.startsAt }
      locale: "nl",
      source: "api",
    },
    { idempotencyKey },
  );
  order.number; // e.g. 1042: show it, the restaurant calls it at pickup
} catch (error) {
  if (error instanceof TaventiApiError && error.code === "pickup_time_unavailable") {
    // the time just filled up: refresh the slots and let the guest choose again
  }
}

5. Follow the order

TypeScript
const { status, pickupAt } = await taventi.getOrderStatus(order.id);
// pending → accepted → preparing → ready → completed (or rejected / cancelled)

Poll every 15–30 seconds while the page is open.

Table booking

TypeScript
const availability = await taventi.getReservationAvailability("beastie-antwerp", {
  date: "2026-12-04",
  partySize: 4,
});
const time = availability.times.find((t) => t.available);

const booking = await taventi.createReservation(
  {
    locationId: availability.locationId,
    startsAt: time.startsAt,
    partySize: 4,
    guest: { name: "Lena", phone: "+32 470 12 34 56", email: "lena@example.com" },
    notes: "A high chair, please",
    locale: "nl",
    source: "api",
  },
  { idempotencyKey: newIdempotencyKey() },
);
booking.status;    // "confirmed", or "pending" while the restaurant confirms by hand
booking.canCancel; // the guest may still cancel online: taventi.cancelReservation(booking.id)

Methods

MethodReturns
getStorefront(subdomain)The restaurant: name, branding, locations.
getLocationMenu(slug)A location with its menu, prices and availability.
getAllergens()The 14 EU allergens, to name products' allergen codes.
priceCart({ locationId, lines })Taventi's prices and total for a cart.
getPickupSlots(slug)Pickup times, and whether orders are taken.
createOrder(order, { idempotencyKey })The order, with its number and status.
getOrderStatus(id)Status and pickup time.
getReservationAvailability(slug, { date, partySize })Free times that day.
createReservation(booking, { idempotencyKey })The booking and its status.
getReservation(id) / cancelReservation(id)A booking, or cancel it.
getStorefrontPage(subdomain, key)The privacy notice or terms.

Each one maps to an endpoint in the API reference, with every field of its answer.

Errors

Failed calls throw a TaventiApiError with the HTTP status, the stable code (e.g. takeaway_closed), a message and sometimes details. Choose what to tell the guest by the code.