Skip to content

Appointments ​

The public booking flow: pick a calendar, a service and a time, hold the slot, book it, optionally pay, then manage the booking.

Quick start ​

Book the first free slot

ts
const calendars = await window.Portal.appointments.appointments();
const calendar = calendars[0];
const services = await window.Portal.appointments.services(calendar.reference_num);
const service = services[0];
const availability = await window.Portal.appointments.availability({ service_reference_num: service.reference_num });

const result = await window.Portal.appointments.book({
  appointment_reference_num: calendar.reference_num,
  service_reference_num: service.reference_num,
  starts_at: availability.slots[0].start,
  customer_name: 'Ada Lovelace',
  customer_email: 'ada@example.com',
});

if (result.requires_payment && result.payment && result.direct_payment_ref && result.booking_reference_num) {
  const pay = await window.Portal.appointments.beginPayment({
    directPaymentRef: result.direct_payment_ref,
    itemRef: result.payment.item_ref,
    amountCents: result.payment.amount_cents,
    bookingRef: result.booking_reference_num,
    accessToken: result.access_token,
    email: 'ada@example.com',
    mountSelector: '#pay',
  });
  await pay.confirm();
}

API reference ​

window.Portal.appointments ​

Portal.appointments — public booking flow: pick a calendar, a service and a time, hold the slot, book it, optionally pay, then manage the booking.

appointment() ​

Reads one calendar.

ts
const appointmentSummary = await window.Portal.appointments.appointment(referenceNum, site);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
sitestringNoThe website's reference.

Returns

Resolves with a PortalAppointmentSummary: One appointment calendar as the public sees it.

appointments() ​

Lists the published appointment calendars (optionally of one website).

ts
const appointmentSummarys = await window.Portal.appointments.appointments(filter);

Parameters

NameTypeRequiredDescription
filterobjectNoAn object, described below.
filter.sitestringNoThe website's reference.

Returns

Resolves with an array of PortalAppointmentSummary.

availability() ​

Free time slots of a service between from and to (ISO dates), optionally for one staff member. Resolves with the calendar's timezone and the slots.

ts
const result = await window.Portal.appointments.availability(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.service_reference_numstringYesThe service's reference.
payload.fromstringNoThe start of the range.
payload.tostringNoThe end of the range.
payload.staff_reference_numstringNoThe staff member's reference.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
timezonestringYesAn IANA timezone, for example Europe/Paris.
slotsPortalAvailabilitySlot[]YesThe free slots.

beginPayment() ​

Mounts the payment form for a booking that requires payment; call confirm() on the result when the visitor presses pay.

ts
const result = await window.Portal.appointments.beginPayment(opts);

Parameters

NameTypeRequiredDescription
optsPortalAppointmentPaymentOptionsYesOptions of Portal.appointments.beginPayment().

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
confirm() => Promise<void>Yes—

book() ​

Creates the booking. When payment is due the result says so (requires_payment, payment).

ts
const appointmentBookResult = await window.Portal.appointments.book(payload);

Parameters

NameTypeRequiredDescription
payloadPortalAppointmentBookPayloadYesWhat Portal.appointments.book() sends.

Returns

Resolves with a PortalAppointmentBookResult: The answer to Portal.appointments.book().

booking() ​

Reads a booking by reference. A guest passes the access_token returned by book().

ts
const result = await window.Portal.appointments.booking(referenceNum, token);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
tokenstringNoA token issued by the server (see the description above).

Returns

Resolves with the server's record as a plain object.

cancelBooking() ​

Cancels a booking. A guest passes the booking's access token.

ts
await window.Portal.appointments.cancelBooking(referenceNum, token);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
tokenstringNoA token issued by the server (see the description above).

Returns

Resolves when the call has completed.

confirmPayment() ​

Tells the server the booking's payment went through, so the booking is confirmed.

ts
await window.Portal.appointments.confirmPayment(bookingRef, token);

Parameters

NameTypeRequiredDescription
bookingRefstringYesThe booking's reference.
tokenstringNoA token issued by the server (see the description above).

Returns

Resolves when the call has completed.

hold() ​

Reserves a slot for a few minutes while the visitor fills in the form. Pass the returned hold_reference_num to book().

ts
const result = await window.Portal.appointments.hold(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.appointment_reference_numstringYes—
payload.service_reference_numstringYesThe service's reference.
payload.starts_atstringYes—
payload.staff_reference_numstringNoThe staff member's reference.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
hold_reference_numstringYesThe reference returned by hold().
expires_atstringNoISO time it expires.

myBookings() ​

The signed-in visitor's own bookings.

ts
const result = await window.Portal.appointments.myBookings();

Returns

Resolves with Array<Record<string, unknown>>.

nextAvailable() ​

The next free slots of a service (count of them), without choosing a date range.

ts
const result = await window.Portal.appointments.nextAvailable(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.service_reference_numstringYesThe service's reference.
payload.countnumberNo—
payload.staff_reference_numstringNoThe staff member's reference.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
slotsPortalAvailabilitySlot[]YesThe free slots.

releaseHold() ​

Gives a held slot back before it expires.

ts
await window.Portal.appointments.releaseHold(holdRef);

Parameters

NameTypeRequiredDescription
holdRefstringYesThe reference returned by hold().

Returns

Resolves when the call has completed.

reschedule() ​

Moves a booking to a new start time (ISO).

ts
const result = await window.Portal.appointments.reschedule(referenceNum, startsAt, token);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
startsAtstringYesThe new start time (ISO).
tokenstringNoA token issued by the server (see the description above).

Returns

Resolves with the server's record as a plain object.

services() ​

The bookable services of a calendar.

ts
const appointmentServices = await window.Portal.appointments.services(referenceNum, site);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
sitestringNoThe website's reference.

Returns

Resolves with an array of PortalAppointmentService.

staff() ​

The staff who can perform the calendar's services, optionally for one service.

ts
const appointmentStaffs = await window.Portal.appointments.staff(referenceNum, serviceRef);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
serviceRefstringNoThe service's reference.

Returns

Resolves with an array of PortalAppointmentStaff.

Types ​

PortalAppointmentBookPayload ​

What Portal.appointments.book() sends.

NameTypeRequiredDescription
appointment_reference_numstringYesThe calendar's reference.
service_reference_numstringYesThe chosen service.
starts_atstringYesISO start time of the chosen slot.
customer_namestringYesThe customer's name.
customer_emailstringYesThe customer's e-mail (confirmations and the guest access token are tied to it).
customer_phonestringNoThe customer's phone number.
notesstringNoFree-text note for the provider.
hold_reference_numstringNoThe hold made with hold(), so the slot cannot be taken meanwhile.
staff_reference_numstringNoThe chosen staff member.
idempotency_keystringNoAny unique string; repeating the call with the same key will not create a second booking.

PortalAppointmentBookResult ​

The answer to Portal.appointments.book().

NameTypeRequiredDescription
successbooleanYesTrue when the booking was created.
booking_reference_numstringNoThe new booking's reference.
statusstringNoThe booking status, for example 'pending_payment' or 'confirmed'.
access_tokenstringNoLets a guest read, pay for, reschedule or cancel this booking later. Keep it.
starts_atstringNoISO start time.
direct_payment_refstringNoThe Direct Payment the charge is made on.
requires_paymentbooleanNoTrue when the visitor must pay before the booking is confirmed.
paymentobjectNoWhat the browser needs to build the invoice; present only when a charge is due.
payment.item_refstringYesThe Direct Payments item reference.
payment.amount_centsnumberYes—
payment.service_namestringYes—
errorobjectNoSet when success is false.
error.messagestringYesA message to show the visitor.
error.codestringYesA code.

PortalAppointmentObject ​

A minimal appointment calendar record (older shape; prefer PortalAppointmentSummary).

NameTypeRequiredDescription
reference_numstringYesThe calendar's reference.
namestringYesInternal name.
titlestringYesPublic title.
created_atstringNoISO creation timestamp.

PortalAppointmentPaymentOptions ​

Options of Portal.appointments.beginPayment().

NameTypeRequiredDescription
directPaymentRefstringYesThe Direct Payment to charge on (direct_payment_ref from book()).
itemRefstringYesThe Direct Payments item the service is mapped to (payment.item_ref from book()).
amountCentsnumberNoAmount hint in cents for a dynamically priced item (payment.amount_cents); a fixed item is priced by Direct Payments.
bookingRefstringYesThe booking being paid for.
accessTokenstringNoThe booking's access token from book(); lets a guest attach the invoice.
emailstringYesThe payer's e-mail (receipt).
mountSelectorstringNoCSS selector of the element the card form is mounted in.
onSuccess() => voidNoCalled when the payment succeeded and the booking is confirmed.
onError(err: Error) => voidNoCalled when the payment failed.

PortalAppointmentService ​

One bookable service of a calendar.

NameTypeRequiredDescription
reference_numstringYesThe service's reference.
namestringYesDisplay name.
descriptionstringNoWhat the service includes.
duration_minutesnumberYesHow long the appointment lasts.
price_centsnumberYesPrice in cents (0 = free).
capacitynumberYesHow many people can book the same slot.

PortalAppointmentStaff ​

A staff member who can take appointments.

NameTypeRequiredDescription
reference_numstringYesThe staff member's reference.
namestringYesDisplay name.

PortalAppointmentSummary ​

One appointment calendar as the public sees it.

NameTypeRequiredDescription
reference_numstringYesThe calendar's reference.
namestringYesInternal name.
titlestringYesPublic title.
timezonestringNoIANA timezone the calendar's times are in, for example 'Europe/Paris'.
descriptionstringNoWhat the calendar is for.
site_usersPortalSiteUsersBlockNoAbsent on an older server bundle; treat as unconnected.

PortalAvailabilitySlot ​

One free time slot returned by availability() or nextAvailable().

NameTypeRequiredDescription
startstringYesISO start time.
endstringYesISO end time.
staff_reference_numstring | nullNoThe staff member the slot is with, or null/absent when any can take it.
remainingnumberYesHow many places are still free in this slot.

PortalSiteUsersBlock ​

The site_users block every connected instance's public config (a store, an event, an appointment calendar) carries. connected: false on an unconnected instance carries no module or path — it must not advertise which Site Users module exists.

NameTypeRequiredDescription
connectedbooleanYesTrue when the instance requires / offers Site Users accounts.
guest_checkoutbooleanYesTrue when a visitor may check out without an account.
modulestringNoThe Site Users module reference (only when connected).
login_pathstring | nullNoPath of the sign-in page.
register_pathstring | nullNoPath of the registration page.
dashboard_pathstring | nullNoPath of the account dashboard.