Reservations

A reservation books a contact into a reservation service at a given start time. Use it to list the calendar, book appointments from your own systems, and move bookings through pending → confirmed → completed (or cancelled / no_show).

Endpoints

MethodPathDescription
GET/reservationsList reservations
GET/reservations/:idGet a reservation
POST/reservationsCreate a reservation
PATCH/reservations/:idUpdate a reservation
DELETE/reservations/:idDelete a reservation

Typical flow

  1. List services (is_active=true).
  2. Get available slots for a service and date.
  3. Create the reservation with the slot start_datetime.
  4. Update it to confirm, reschedule, complete or cancel.

Date and time format

start_datetime and end_datetime are wall-clock times in the service's timezone, stored with a Z suffix. 2026-04-25T15:00:00.000Z means 15:00 local time of the service, not 15:00 UTC. Any offset you send is stripped and the clock time is kept (2026-04-25T15:00:00-05:00 is stored as 2026-04-25T15:00:00.000Z). The slots returned by available slots already use this format.

Payments

Services with payment_mode deposit or full (or optional when the booking sends payment_choice: "pay_now") collect online payments through the organization's payment gateway. Reservations created through the API (source other than manual) for those services start as status: "awaiting_payment" with payment_status: "pending" and payment_expires_at = now + the service payment_hold_minutes; the create response then also includes pay_url (link to send to the customer), payment_required and payment_unavailable_reason. Reservations with source: "manual" are only held for payment when the body includes "collect_payment": true. When the payment arrives the reservation becomes confirmed (or pending when the service does not auto-confirm) and payment_status becomes deposit_paid or paid. When the organization cannot collect online (no active gateway, unsupported currency) the reservation is created normally with payment_choice: "pay_later" and payment_unavailable_reason explains why.

The reservation object

json

service, contact and assigned_resources are joined on every read and write response; they are not columns and cannot be written. service is the full service object and resource the full resource object (shortened above).

Fields

FieldTypeDescription
idintegerRead-only. Unique ID.
organization_idintegerOrganization that owns the reservation. Required on create; must be the API key's organization.
service_idintegerReservation service booked. Required on create.
contact_idintegerContact the reservation is for. Required on create.
party_sizeintegerNumber of people. Minimum 1, default 1. Cannot exceed the service max_party_size.
start_datetimestring (date-time)Start, as service wall-clock time (see above). Required on create.
end_datetimestring (date-time)End. Computed from start_datetime + service duration_minutes when omitted on create, and recalculated whenever start_datetime or service_id changes.
statusstringOne of pending, confirmed, awaiting_payment, cancelled, completed, no_show. Default pending; forced to confirmed on create when the service has auto_confirm: true. awaiting_payment is set by the server when the booking must be paid online first (see Payments): it holds the slot until payment_expires_at, then becomes cancelled with cancellation_reason: "payment_expired".
sourcestringWhere the booking came from: manual, whatsapp_ai, instagram_ai, webchat, public_link, api, automation (automations). Default manual.
conversation_idinteger | nullConversation where the booking originated.
deal_idinteger | nullRelated deal.
company_idinteger | nullRelated company.
estimate_idinteger | nullRelated estimate.
invoice_idinteger | nullRelated invoice.
google_meet_linkstring | nullVideo-call link. Included in the confirmation and reminder emails when set. The API does not generate it.
confirmation_sent_atstring (date-time) | nullRead-only in practice. Set when the confirmation email is sent to the contact.
reminders_sentarrayRead-only in practice. Reminder emails already sent, as { "key", "sent_at" } items. Reset to [] when start_datetime changes so reminders are sent again for the new time.
cancelled_atstring (date-time) | nullWhen it was cancelled. Not set automatically: send it together with status: "cancelled".
cancelled_bystring | nullOne of customer, organization, system.
cancellation_reasonstring | nullFree-text cancellation reason.
customer_notesstring | nullNotes from the customer.
internal_notesstring | nullInternal staff notes.
payment_statusstringOne of none, not_required, pending, deposit_paid, paid, partially_refunded, refunded, expired (none and not_required mean no payment is expected). Set by the server for services with online payments: pending while something is due, deposit_paid / paid after payment, expired when an unpaid hold expires. When omitted on create for a service without payments the stored default is not_required.
payment_amountstring (decimal) | nullAmount paid or due (returned as a decimal string, for example "150.00"). Minimum 0. Used as the purchase amount when loyalty points are awarded on completion.
preferred_resource_idinteger | nullResource the customer asked for. On create, availability is checked only against this resource.
duration_minutesinteger | nullLength chosen by the customer for services with duration_mode: "flexible"; must be one of the service duration_options. null = the service duration_minutes. Used for end_datetime and the price.
amount_totalnumber | nullRead-only in practice. Price of the booking computed from the service price and pricing_unit (per booking, × party_size or × hours). Recomputed when the service, party size or duration change while nothing has been paid. null when the service has no price.
amount_due_nownumber | nullRead-only in practice. What the online payment charges: the deposit (payment_mode: "deposit") or the total (full, or optional with payment_choice: "pay_now").
amount_paidnumberRead-only in practice. Total paid so far, from payment links and payments recorded in the app. Default 0.
system_currency_idinteger | nullRead-only. Currency of the amounts (the service currency).
payment_choicestring | nullpay_now or pay_later. For services with payment_mode: "optional" it decides whether the customer pays online now; also set to pay_later when online payment is not available.
payment_expires_atstring (date-time) | nullRead-only. Real UTC time (not wall-clock) until which an awaiting_payment booking holds its slot.
payment_link_idinteger | nullRead-only. Payment link created for the online payment.
needs_refundbooleanRead-only in practice. true when a paid booking was cancelled by the customer, or a payment arrived after the slot was taken, and the money should be returned. Default false.
refunded_amountnumber | nullRead-only in practice. Amount marked as refunded in the app (bookkeeping only, no gateway refund).
refunded_atstring (date-time) | nullRead-only in practice. When the refund was recorded.
created_by_user_idinteger | nullRead-only. User who created it; with an API key, the user the key belongs to.
custom_fields_by_keyobjectReservation custom field values keyed by field key (fields with entity_type: "reservation"). On update, keys are merged into the existing values; send null to clear a key. Unknown keys return 400.
custom_fields_by_nameobjectRead-only. Same values keyed by field name. Derived from custom_fields_by_key.
custom_fields_meta_dataarrayRead-only. One item per value: custom_field_id, custom_field_key, custom_field_name, custom_field_value. Derived from custom_fields_by_key.
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 reservation is deleted; deleted reservations are not returned.

Side effects

  • Create: the slot is validated (see Create a reservation), linked resources are assigned (assigned_resources), the confirmation email is sent to the contact and a notification to staff resources linked to a user (both on by default, configurable in the organization's reservation settings), and New reservation automations run.
  • Update: Reservation updated automations run; moving to completed awards loyalty points or stamps to the contact when the organization has an active loyalty program.
  • Reminders: reminder emails are sent automatically before start_datetime according to the organization's reservation settings and recorded in reminders_sent.
  • No email is sent for reservations in cancelled or no_show status.

Related

Report an issue with this documentation

Please log in to report issues with our documentation.