API functions

All functions are exported from @zaptime/core (book, reserve, confirm, cancel are re-exported by @zaptime/vue3). They read the token, base URL, selected time slot and timezone from the composable state of the given calendarId.

fetchRemoteConfiguration

Fetches the dashboard configuration of an event type. Never throws; returns a ts-results-es Result.

fetchRemoteConfiguration(
  token: string,
  apiBaseUrl?: string,
  reservationUuid?: string,
): Promise<Result<InitData, "invalidToken">>

const result = await fetchRemoteConfiguration(token);

if (result.isErr()) {
  // result.error === "invalidToken" (also returned on network failure)
}

const data = result.value;

InitData:

Key	Type	Description
configuration	ZaptimeConfig without token	Dashboard config: locale texts, theme, min, max, closestBookableDay, ...
disabled	boolean	Event type disabled in the dashboard.
eventTypeName	string
locations	Location[]
customFields	CustomField[]	Booking form schema.
maxGuests	number | null
stripeConfig	StripeConfig	Present for paid event types.
reservation	Reservation	Present when reservationUuid was passed.
isSubscribed	boolean	Account has a paid plan (controls the "Powered by Zaptime" badge).
analytics	Analytics[]	Tracking plugins configured in the dashboard.

book

book(options: {
  email: string;
  firstName?: string;
  lastName?: string;
  phone?: string;
  seats?: number; // default 1
  location?: Location; // default: first location of the event type
  customFields?: CustomFieldCollected[];
  guests?: string[];
  calendarId?: string;
}): Promise<ReservationResponse>

Books the selected time slot. Throws SlotNoLongerAvailableError on HTTP 409, otherwise Error when no slot is selected or the request fails. Navigates to config.redirectAfterBookingUrl after success when it is set.

reserve

Same options as book. Holds the slot and refreshes the hold every 15 minutes until confirm, cancel or stopReservationRefresh is called.

reserve(options): Promise<ReservationResponse>

confirm

confirm(options?: {
  calendarId?: string;
  firstName?: string;
  lastName?: string;
  phone?: string;
  customFields?: CustomFieldCollected[];
  guests?: string[];
}): Promise<ReservationResponse>

Confirms the held reservation and stops the refresh. Throws when nothing is reserved.

cancel

cancel(calendarId?: string): Promise<boolean>

Cancels the held reservation and stops the refresh. Resolves false when nothing is reserved.

reschedule

reschedule(calendarId?: string): Promise<ReservationResponse>

Moves the reservation from useReservationReschedule to the selected time slot. Sends config.rescheduleOverrideToken when present. Throws RescheduleNotAllowedError on HTTP 403.

stopReservationRefresh

stopReservationRefresh(): void

Stops the reserve refresh interval. Call it on unmount.

Errors

import { SlotNoLongerAvailableError, RescheduleNotAllowedError } from "@zaptime/core";

Class	HTTP	Meaning	Recommended handling
SlotNoLongerAvailableError	409	The slot was taken or no host can serve it anymore.	Show slotNoLongerAvailableText(locale), call getDays(), let the attendee pick again.
RescheduleNotAllowedError	403	Notice period violated, reservation already started, or rescheduling disabled.	Show rescheduleNotAllowedText(locale).

ReservationResponse

interface ReservationResponse {
  success: boolean; // false on validation failure
  data: {
    uuid: string;
    userId: number;
    userName: string;
    userEmail: string;
  };
}

Text helpers

import { slotNoLongerAvailableText, rescheduleNotAllowedText } from "@zaptime/core";

slotNoLongerAvailableText(config.locale); // localized, English fallback
rescheduleNotAllowedText(config.locale);