Skip to content

API Reference

Bookings

Create, manage, and cancel bookings via the API.

Hold a Slot

Before creating a booking, place a hold on the time slot to prevent double bookings.

POST /api/v1/bookings/hold

Request Body

Field Type Required Description
service_id uuid Yes The service being booked
location_id uuid Yes The location
staff_id uuid No Preferred staff member
starts_at datetime Yes Slot start time (ISO 8601, must be in the future)

Example

curl -X POST https://calendence.com/api/v1/bookings/hold \
  -H "Authorization: Bearer cal_ses_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "uuid",
    "location_id": "uuid",
    "starts_at": "2026-03-25T14:00:00+00:00"
  }'

Response (201)

{
  "hold_id": "uuid",
  "service_id": "uuid",
  "location_id": "uuid",
  "starts_at": "2026-03-25T14:00:00+00:00",
  "ends_at": "2026-03-25T14:30:00+00:00",
  "expires_at": "2026-03-25T13:10:00+00:00"
}

Holds expire after 10 minutes. If the slot is already held by another session, a 409 Conflict is returned.

Create a Booking

Convert a hold into a confirmed booking.

POST /api/v1/bookings

Request Body

Field Type Required Description
hold_id uuid Yes The active hold to convert
client.first_name string Yes Client's first name
client.last_name string Yes Client's last name
client.email string Yes Client's email
client.phone string No Client's phone number
custom_field_values array No Custom field responses
notes string No Client notes (max 1000 chars)

Example

curl -X POST https://calendence.com/api/v1/bookings \
  -H "Authorization: Bearer cal_ses_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "hold_id": "uuid",
    "client": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone": "+15551234567"
    },
    "notes": "Please use the side entrance"
  }'

Response (201)

Returns the full booking resource with service, location, client, and staff details.

If the hold has expired, a 404 is returned. If the service requires a deposit, the response includes a redirect_url to Stripe Checkout.

Show a Booking

GET /api/v1/bookings/{id}

Available to all key types. Returns the booking with relationships.

Update a Booking

PATCH /api/v1/bookings/{id}

Requires a business or hub API key — not available to session tokens.

Field Type Description
starts_at datetime Reschedule start time
ends_at datetime Reschedule end time
status string pending, confirmed, in_progress, completed, cancelled
notes string Updated notes

Cancel a Booking

DELETE /api/v1/bookings/{id}

Requires a business or hub API key. Sets status to cancelled and records cancelled_at. Triggers the booking.cancelled webhook event.