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
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.
const appointmentSummary = await window.Portal.appointments.appointment(referenceNum, site);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
site | string | No | The 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).
const appointmentSummarys = await window.Portal.appointments.appointments(filter);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
filter | object | No | An object, described below. |
filter.site | string | No | The 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.
const result = await window.Portal.appointments.availability(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.service_reference_num | string | Yes | The service's reference. |
payload.from | string | No | The start of the range. |
payload.to | string | No | The end of the range. |
payload.staff_reference_num | string | No | The staff member's reference. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
timezone | string | Yes | An IANA timezone, for example Europe/Paris. |
slots | PortalAvailabilitySlot[] | Yes | The free slots. |
beginPayment()
Mounts the payment form for a booking that requires payment; call confirm() on the result when the visitor presses pay.
const result = await window.Portal.appointments.beginPayment(opts);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
opts | PortalAppointmentPaymentOptions | Yes | Options of Portal.appointments.beginPayment(). |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
confirm | () => Promise<void> | Yes | — |
book()
Creates the booking. When payment is due the result says so (requires_payment, payment).
const appointmentBookResult = await window.Portal.appointments.book(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | PortalAppointmentBookPayload | Yes | What 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().
const result = await window.Portal.appointments.booking(referenceNum, token);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
token | string | No | A 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.
await window.Portal.appointments.cancelBooking(referenceNum, token);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
token | string | No | A 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.
await window.Portal.appointments.confirmPayment(bookingRef, token);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
bookingRef | string | Yes | The booking's reference. |
token | string | No | A 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().
const result = await window.Portal.appointments.hold(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.appointment_reference_num | string | Yes | — |
payload.service_reference_num | string | Yes | The service's reference. |
payload.starts_at | string | Yes | — |
payload.staff_reference_num | string | No | The staff member's reference. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
hold_reference_num | string | Yes | The reference returned by hold(). |
expires_at | string | No | ISO time it expires. |
myBookings()
The signed-in visitor's own bookings.
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.
const result = await window.Portal.appointments.nextAvailable(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.service_reference_num | string | Yes | The service's reference. |
payload.count | number | No | — |
payload.staff_reference_num | string | No | The staff member's reference. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
slots | PortalAvailabilitySlot[] | Yes | The free slots. |
releaseHold()
Gives a held slot back before it expires.
await window.Portal.appointments.releaseHold(holdRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
holdRef | string | Yes | The reference returned by hold(). |
Returns
Resolves when the call has completed.
reschedule()
Moves a booking to a new start time (ISO).
const result = await window.Portal.appointments.reschedule(referenceNum, startsAt, token);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
startsAt | string | Yes | The new start time (ISO). |
token | string | No | A 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.
const appointmentServices = await window.Portal.appointments.services(referenceNum, site);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
site | string | No | The website's reference. |
Returns
Resolves with an array of PortalAppointmentService.
staff()
The staff who can perform the calendar's services, optionally for one service.
const appointmentStaffs = await window.Portal.appointments.staff(referenceNum, serviceRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
serviceRef | string | No | The service's reference. |
Returns
Resolves with an array of PortalAppointmentStaff.
Types
PortalAppointmentBookPayload
What Portal.appointments.book() sends.
| Name | Type | Required | Description |
|---|---|---|---|
appointment_reference_num | string | Yes | The calendar's reference. |
service_reference_num | string | Yes | The chosen service. |
starts_at | string | Yes | ISO start time of the chosen slot. |
customer_name | string | Yes | The customer's name. |
customer_email | string | Yes | The customer's e-mail (confirmations and the guest access token are tied to it). |
customer_phone | string | No | The customer's phone number. |
notes | string | No | Free-text note for the provider. |
hold_reference_num | string | No | The hold made with hold(), so the slot cannot be taken meanwhile. |
staff_reference_num | string | No | The chosen staff member. |
idempotency_key | string | No | Any unique string; repeating the call with the same key will not create a second booking. |
PortalAppointmentBookResult
The answer to Portal.appointments.book().
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when the booking was created. |
booking_reference_num | string | No | The new booking's reference. |
status | string | No | The booking status, for example 'pending_payment' or 'confirmed'. |
access_token | string | No | Lets a guest read, pay for, reschedule or cancel this booking later. Keep it. |
starts_at | string | No | ISO start time. |
direct_payment_ref | string | No | The Direct Payment the charge is made on. |
requires_payment | boolean | No | True when the visitor must pay before the booking is confirmed. |
payment | object | No | What the browser needs to build the invoice; present only when a charge is due. |
payment.item_ref | string | Yes | The Direct Payments item reference. |
payment.amount_cents | number | Yes | — |
payment.service_name | string | Yes | — |
error | object | No | Set when success is false. |
error.message | string | Yes | A message to show the visitor. |
error.code | string | Yes | A code. |
PortalAppointmentObject
A minimal appointment calendar record (older shape; prefer PortalAppointmentSummary).
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The calendar's reference. |
name | string | Yes | Internal name. |
title | string | Yes | Public title. |
created_at | string | No | ISO creation timestamp. |
PortalAppointmentPaymentOptions
Options of Portal.appointments.beginPayment().
| Name | Type | Required | Description |
|---|---|---|---|
directPaymentRef | string | Yes | The Direct Payment to charge on (direct_payment_ref from book()). |
itemRef | string | Yes | The Direct Payments item the service is mapped to (payment.item_ref from book()). |
amountCents | number | No | Amount hint in cents for a dynamically priced item (payment.amount_cents); a fixed item is priced by Direct Payments. |
bookingRef | string | Yes | The booking being paid for. |
accessToken | string | No | The booking's access token from book(); lets a guest attach the invoice. |
email | string | Yes | The payer's e-mail (receipt). |
mountSelector | string | No | CSS selector of the element the card form is mounted in. |
onSuccess | () => void | No | Called when the payment succeeded and the booking is confirmed. |
onError | (err: Error) => void | No | Called when the payment failed. |
PortalAppointmentService
One bookable service of a calendar.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The service's reference. |
name | string | Yes | Display name. |
description | string | No | What the service includes. |
duration_minutes | number | Yes | How long the appointment lasts. |
price_cents | number | Yes | Price in cents (0 = free). |
capacity | number | Yes | How many people can book the same slot. |
PortalAppointmentStaff
A staff member who can take appointments.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The staff member's reference. |
name | string | Yes | Display name. |
PortalAppointmentSummary
One appointment calendar as the public sees it.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The calendar's reference. |
name | string | Yes | Internal name. |
title | string | Yes | Public title. |
timezone | string | No | IANA timezone the calendar's times are in, for example 'Europe/Paris'. |
description | string | No | What the calendar is for. |
site_users | PortalSiteUsersBlock | No | Absent on an older server bundle; treat as unconnected. |
PortalAvailabilitySlot
One free time slot returned by availability() or nextAvailable().
| Name | Type | Required | Description |
|---|---|---|---|
start | string | Yes | ISO start time. |
end | string | Yes | ISO end time. |
staff_reference_num | string | null | No | The staff member the slot is with, or null/absent when any can take it. |
remaining | number | Yes | How 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.
| Name | Type | Required | Description |
|---|---|---|---|
connected | boolean | Yes | True when the instance requires / offers Site Users accounts. |
guest_checkout | boolean | Yes | True when a visitor may check out without an account. |
module | string | No | The Site Users module reference (only when connected). |
login_path | string | null | No | Path of the sign-in page. |
register_path | string | null | No | Path of the registration page. |
dashboard_path | string | null | No | Path of the account dashboard. |