Skip to main content

​
Create Booking by Customer

Customers can create new appointments or join existing group bookings (events/classes). 
curl -X POST https://api.example.com/bookings/customer \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_name": "spa-retreat",
    "service_id": 123,
    "location_id": 456,
    "timeStamp": "2026-03-15T14:00:00Z",
    "customer_note": "Please use fragrance-free products"
  }'

​
Request Parameters

​
merchant_name
string
required
Unique identifier for the merchant
​
service_id
integer
required
ID of the service to book
​
location_id
integer
required
ID of the location where the service will be provided
​
timeStamp
string
required
ISO 8601 timestamp for the booking start time
​
customer_note
string
Optional note from the customer with special requests or information
​
booking_id
integer
For group bookings only: ID of the existing group booking to join. Omit this field when creating a new appointment.

​
Response

Returns 201 Created on success with no response body.
Joining Group Bookings: To join an existing event or class, include the booking_id parameter. This adds the customer as a participant to the group booking.

​
Create Booking by Merchant

Merchants can create bookings on behalf of customers, including appointments, events, classes, and recurring bookings. 
curl -X POST https://api.example.com/bookings/merchant \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": 123,
    "timestamp": "2026-03-15T14:00:00Z",
    "customers": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "[email protected]",
        "phone_number": "+1234567890"
      }
    ],
    "merchant_note": "Customer prefers morning appointments",
    "is_recurring": false
  }'

​
Request Parameters

​
service_id
integer
required
ID of the service to book
​
timestamp
string
required
ISO 8601 timestamp for the booking start time
​
customers
array
required
Array of customer objects to include in the booking
​
customers[].id
uuid
Existing customer ID. If provided, other fields are optional and will be ignored.
​
customers[].first_name
string
Customer’s first name (required for new customers)
​
customers[].last_name
string
Customer’s last name
​
customers[].email
string
Customer’s email address
​
customers[].phone_number
string
Customer’s phone number
​
merchant_note
string
Internal notes about the booking
​
is_recurring
boolean
required
Set to true to create a recurring booking series
​
recurrence_rule
object
Required when is_recurring is true. Defines the recurrence pattern.
​
recurrence_rule.frequency
string
Recurrence frequency: DAILY, WEEKLY, MONTHLY, or YEARLY
​
recurrence_rule.interval
integer
Interval between occurrences (e.g., 2 for every 2 weeks)
​
recurrence_rule.weekdays
array
Array of weekday strings: MO, TU, WE, TH, FR, SA, SU
​
recurrence_rule.until
string
ISO 8601 timestamp for when the recurrence ends

​
Response

Returns 201 Created on success with no response body.

​
Creating Recurring Bookings

Recurring bookings are perfect for classes that meet on a regular schedule. 
curl -X POST https://api.example.com/bookings/merchant \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": 789,
    "timestamp": "2026-03-15T18:00:00Z",
    "customers": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "merchant_note": "Yoga class - beginner level",
    "is_recurring": true,
    "recurrence_rule": {
      "frequency": "WEEKLY",
      "interval": 1,
      "weekdays": ["MO", "WE", "FR"],
      "until": "2026-06-15T18:00:00Z"
    }
  }'
Recurrence Rules: The system follows the iCalendar (RFC 5545) specification for recurrence rules. This allows for flexible scheduling patterns.

​
Group Booking vs Appointment

​
Creating an Appointment

Appointments are one-on-one bookings with a single customer: 
{
  "service_id": 123,
  "timestamp": "2026-03-15T14:00:00Z",
  "customers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "is_recurring": false
}

​
Creating a Group Booking (Event/Class)

Group bookings can have multiple participants: 
{
  "service_id": 456,
  "timestamp": "2026-03-15T14:00:00Z",
  "customers": [
    {"id": "550e8400-e29b-41d4-a716-446655440000"},
    {"id": "660e8400-e29b-41d4-a716-446655440001"},
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]"
    }
  ],
  "is_recurring": false
}
The booking type (appointment, event, or class) is determined by the service configuration and whether the booking is recurring.

​
Error Responses

The API returns standard HTTP error codes:
Status CodeDescription
400 Bad RequestInvalid parameters or validation error
401 UnauthorizedMissing or invalid authentication token
404 Not FoundService, location, or customer not found
409 ConflictTime slot already booked or capacity reached
Capacity Limits: Group bookings have minimum and maximum participant limits. The API will return an error if you attempt to exceed the maximum capacity.

Build docs developers (and LLMs) love

Get started for freeTalk to us