JS client
The @bookitive/js typed client for building your own checkout — reads, placing orders, phone verification, waitlist, live seat updates, and typed errors.
@bookitive/js is the headless companion to the
widget: where the widget gives you the
seat-map UI, this package gives you the raw typed API for building
your own checkout from scratch. Every request and response type is
generated from the backend's OpenAPI spec, so they can't drift.
npm i @bookitive/jsReading data
import { BookitiveClient } from '@bookitive/js';
const client = new BookitiveClient({
baseUrl: 'https://api.bookitive.com',
org: 'city-theatre',
event: 'spring-gala-2027',
});
const event = await client.event(); // identity, branding, priced ticket types
const seating = await client.seating(); // floors → sections → tables, seats, GA areas
const availability = await client.availability(); // current sellability snapshot
const preview = await client.discount('SPRING10'); // validate a promo codePass your framework's fetch to the constructor for SSR.
Placing an order
checkout() places a reservation: seats are held atomically for the
event's hold TTL, and payment instructions are emailed to the buyer and
returned to you.
import { BookitiveError, checkoutErrorMessage } from '@bookitive/js';
try {
const order = await client.checkout({
customer: { name: 'Jana Nováková', email: 'jana@example.com' },
items: [
{ ticketTypeId: '…', seatId: '…', quantity: 1 }, // a seat
{ ticketTypeId: '…', gaAreaId: '…', quantity: 2 }, // standing
],
// discountCode, verificationToken, captchaToken, …
});
} catch (err) {
if (err instanceof BookitiveError && err.isConflict) {
// a seat was taken mid-checkout — refresh and reselect
}
}Phone verification and waitlist
verifyStart(phone, captchaToken?)andverifyCheck(phone, code)mint the single-useverificationTokenyou pass tocheckout()for phone-verified events.joinWaitlist(req)adds a buyer to a sold-out type's waitlist.
Live seat updates
live() opens a websocket for real-time seat changes — essential for a
custom seat map that must stay honest:
const sub = client.live({
onStartstate: (snapshot) => {}, // full state on every (re)connect — your resync point
onSeat: (delta) => {}, // per-seat changes after that
onConnectionChange: (connected) => {}, // boolean — true on connect, false on drop
});It fires a full startstate snapshot on every connect and reconnect
(auto-reconnect with jittered backoff), so you resync cleanly after any
network blip rather than drifting.
Typed errors
BookitiveError carries status, a runtime type enum you can compare
(err.type === …), per-code fields (e.g. order limits), and the
isConflict shortcut. checkoutErrorMessage(err, locale) returns
buyer-ready Czech/English copy for known errors, or undefined for ones
you should handle yourself.
This is the public API — it does only what a buyer could do (read the event, hold seats, verify a phone). For server-side reads across your whole organization, that's the partner API with a secret key.
Related
Embed the widget
Embed the Bookitive seat map and checkout on your own site — the loader, every mount option, the events it emits, the controller API, and the captcha-safe checkout.
Partner API
Server-side access with two credential types — read-only API keys for your systems and scan-only device credentials for gates — with rate limits and IP controls.