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
| Method | Path | Description |
|---|---|---|
GET | /reservations | List reservations |
GET | /reservations/:id | Get a reservation |
POST | /reservations | Create a reservation |
PATCH | /reservations/:id | Update a reservation |
DELETE | /reservations/:id | Delete a reservation |
Typical flow
- List services (
is_active=true). - Get available slots for a service and date.
- Create the reservation with the slot
start_datetime. - 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
| Field | Type | Description |
|---|---|---|
id | integer | Read-only. Unique ID. |
organization_id | integer | Organization that owns the reservation. Required on create; must be the API key's organization. |
service_id | integer | Reservation service booked. Required on create. |
contact_id | integer | Contact the reservation is for. Required on create. |
party_size | integer | Number of people. Minimum 1, default 1. Cannot exceed the service max_party_size. |
start_datetime | string (date-time) | Start, as service wall-clock time (see above). Required on create. |
end_datetime | string (date-time) | End. Computed from start_datetime + service duration_minutes when omitted on create, and recalculated whenever start_datetime or service_id changes. |
status | string | One 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". |
source | string | Where the booking came from: manual, whatsapp_ai, instagram_ai, webchat, public_link, api, automation (automations). Default manual. |
conversation_id | integer | null | Conversation where the booking originated. |
deal_id | integer | null | Related deal. |
company_id | integer | null | Related company. |
estimate_id | integer | null | Related estimate. |
invoice_id | integer | null | Related invoice. |
google_meet_link | string | null | Video-call link. Included in the confirmation and reminder emails when set. The API does not generate it. |
confirmation_sent_at | string (date-time) | null | Read-only in practice. Set when the confirmation email is sent to the contact. |
reminders_sent | array | Read-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_at | string (date-time) | null | When it was cancelled. Not set automatically: send it together with status: "cancelled". |
cancelled_by | string | null | One of customer, organization, system. |
cancellation_reason | string | null | Free-text cancellation reason. |
customer_notes | string | null | Notes from the customer. |
internal_notes | string | null | Internal staff notes. |
payment_status | string | One 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_amount | string (decimal) | null | Amount 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_id | integer | null | Resource the customer asked for. On create, availability is checked only against this resource. |
duration_minutes | integer | null | Length 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_total | number | null | Read-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_now | number | null | Read-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_paid | number | Read-only in practice. Total paid so far, from payment links and payments recorded in the app. Default 0. |
system_currency_id | integer | null | Read-only. Currency of the amounts (the service currency). |
payment_choice | string | null | pay_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_at | string (date-time) | null | Read-only. Real UTC time (not wall-clock) until which an awaiting_payment booking holds its slot. |
payment_link_id | integer | null | Read-only. Payment link created for the online payment. |
needs_refund | boolean | Read-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_amount | number | null | Read-only in practice. Amount marked as refunded in the app (bookkeeping only, no gateway refund). |
refunded_at | string (date-time) | null | Read-only in practice. When the refund was recorded. |
created_by_user_id | integer | null | Read-only. User who created it; with an API key, the user the key belongs to. |
custom_fields_by_key | object | Reservation 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_name | object | Read-only. Same values keyed by field name. Derived from custom_fields_by_key. |
custom_fields_meta_data | array | Read-only. One item per value: custom_field_id, custom_field_key, custom_field_name, custom_field_value. Derived from custom_fields_by_key. |
created_at | string (date-time) | Read-only. Creation time. |
updated_at | string (date-time) | Read-only. Last update time. |
deleted_at | string (date-time) | null | Read-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
completedawards loyalty points or stamps to the contact when the organization has an active loyalty program. - Reminders: reminder emails are sent automatically before
start_datetimeaccording to the organization's reservation settings and recorded inreminders_sent. - No email is sent for reservations in
cancelledorno_showstatus.
Related
Report an issue with this documentation
Please log in to report issues with our documentation.