Reservation services

A reservation service is something customers can book (a consultation, a table, a class): its duration, how many bookings fit in one slot, booking-window rules, price and whether it shows on public booking pages. Every reservation belongs to one service.

Endpoints

MethodPathDescription
GET/reservation-servicesList services
GET/reservation-services/:idGet a service
POST/reservation-servicesCreate a service
PATCH/reservation-services/:idUpdate a service
DELETE/reservation-services/:idDelete a service

The service object

json

Fields

FieldTypeDescription
idintegerRead-only. Unique ID.
organization_idintegerOwning organization. Required on create; must be the API key's organization.
namestringService name, max 255 characters. Required on create.
descriptionstring | nullDescription shown on booking pages.
duration_minutesintegerLength of one booking, minimum 1. Required on create. Used to compute the reservation end_datetime and the slots. With duration_mode: "flexible" it is the default length when the reservation does not send duration_minutes.
buffer_before_minutesintegerDefault 0. Free minutes kept before each booking: a slot is not offered when this gap overlaps another booking of the same resources or service.
buffer_after_minutesintegerDefault 0. Free minutes kept after each booking, same rule as buffer_before_minutes.
slot_capacityintegerHow much fits in the same time slot. Default 1, minimum 1. Counted in reservations when capacity_unit is bookings, in people (sum of party_size) when it is people.
max_party_sizeintegerMaximum party_size per reservation. Default 1, minimum 1.
capacity_modestringper_slot (default) or per_resource. With per_slot, creating a reservation fails when slot_capacity overlapping reservations already exist; with per_resource that check is skipped and only the linked resources' capacity applies. Available slots always count against slot_capacity.
pricestring (decimal) | nullPrice, minimum 0. Returned as a decimal string. Send a number.
currency_idinteger | nullOrganization currency (organization_currencies ID) of price. When set and exchange_rate is not sent, the server fills exchange_rate and the formatting fields below.
exchange_ratestring (decimal) | nullRate from this currency to the organization's base currency. Filled automatically from currency_id unless you send it.
currency_symbolstring | nullCurrency symbol, e.g. $. Filled from currency_id when empty.
currency_formatstring | nullDisplay pattern, e.g. {symbol}{amount}. Filled from currency_id when empty.
decimal_placesinteger | nullDecimals to display. Default 2.
thousand_separatorstring | nullDefault ,.
decimal_separatorstring | nullDefault ..
max_daily_bookingsinteger | nullMaximum pending/confirmed reservations per day for this service, minimum 1. null = no limit. Enforced on create.
max_advance_daysintegerHow many days ahead customers can book. Default 30, minimum 1.
min_advance_hoursintegerMinimum notice in hours before a booking starts. Default 1, minimum 0. Applies to customer and AI bookings; staff bookings (source: "manual") skip it.
requires_confirmationbooleanDefault false. Stored setting; the initial status is controlled by auto_confirm.
auto_confirmbooleanDefault true. When true, new reservations are created as confirmed; otherwise the status sent on create is kept (default pending).
allow_cancellationbooleanDefault true. Whether the customer can cancel from the booking's manage link. Staff and the API can always cancel.
cancellation_deadline_hoursintegerDefault 24, minimum 0. The customer can cancel from the manage link until this many hours before the start. Not enforced for staff or the API.
is_publicbooleanDefault true. Only services with is_public: true and is_active: true appear on booking links.
booking_instructionsstring | nullInstructions shown on the public booking page.
colorstring | nullCalendar color (hex), max 50 characters.
image_urlstring | nullImage URL shown on booking pages.
video_urlstring | nullVideo shown on the public booking page, max 2000 characters. Accepts YouTube, Vimeo, Loom, Wistia, Google Drive, Dropbox and other embeddable links, an <iframe> embed code, or a direct video file URL; unsupported links return 400.
is_activebooleanDefault true. Inactive services cannot be booked and return no slots.
product_idinteger | nullOptional link to a product.
timezonestring | nullIANA timezone of the service, e.g. America/New_York. Default UTC; while it is UTC the organization timezone is used when the organization has one. Reservation times are wall-clock times in this zone.
slot_intervalintegerMinutes between consecutive slot start times. Default 30, minimum 5.
duration_modestringfixed (default: every booking lasts duration_minutes) or flexible (the customer picks one of duration_options).
duration_optionsarray of integersLengths in minutes the customer can choose when duration_mode is flexible, e.g. [120, 240, 480]. Each between 5 and 10080, up to 24 items. When empty on a flexible service, [duration_minutes] is stored.
capacity_unitstringbookings (default: each reservation uses 1 of slot_capacity) or people (each reservation uses its party_size, e.g. a restaurant with 20 seats).
min_party_sizeintegerMinimum party_size per reservation. Default 1. Cannot be greater than max_party_size (400 otherwise).
pricing_unitstringHow price is applied: per_booking (default), per_person (× party_size) or per_hour (× booked minutes / 60).
payment_modestringnone (default: no online payment), optional (the customer chooses pay now or pay at the venue), deposit (part of the total is paid online to confirm) or full (the whole total is paid online to confirm).
deposit_typestringpercent (default) or fixed. Used when payment_mode is deposit.
deposit_valuenumber | nullDeposit as a percent of the total (0–100) or a fixed amount in the service currency. Required and greater than 0 when payment_mode is deposit.
payment_hold_minutesintegerDefault 30 (5–10080). How long an unpaid online booking (status: "awaiting_payment") keeps its slot before it is cancelled with cancellation_reason: "payment_expired".
payment_gateway_idinteger | nullOrganization payment gateway used for payment links. null = the organization default gateway. Must belong to the same organization.
allow_customer_reschedulebooleanDefault false. Whether the customer can move the booking from its manage link.
reschedule_deadline_hoursinteger | nullThe customer can reschedule until this many hours before the start. null = until it starts.
cancellation_policy_textstring | nullPolicy shown to the customer before booking and paying, max 5000 characters.
created_atstring (date-time)Read-only. Creation time.
updated_atstring (date-time)Read-only. Last update time.
deleted_atstring (date-time) | nullRead-only. Set when the service is deleted.

Related

Report an issue with this documentation

Please log in to report issues with our documentation.