Skip to main content

​
Get Booking by Customer

Customers can retrieve details about their bookings. 
curl -X GET https://api.example.com/bookings/customer/123 \
  -H "Authorization: Bearer TOKEN"

​
Response Fields

​
from_date
timestamp
required
Start date and time of the booking
​
to_date
timestamp
required
End date and time of the booking
​
service_name
string
required
Name of the booked service
​
cancel_deadline
integer
required
Hours before booking when cancellation is allowed
​
formatted_location
string
required
Human-readable location address
​
price
FormattedPrice
required
Price information with currency formatting
​
price_type
string
required
Type of pricing: per_person, per_booking, or free
​
merchant_name
string
required
Name of the merchant providing the service
​
is_cancelled
boolean
required
Whether the booking has been cancelled

​
Example Response

{
  "from_date": "2026-03-15T14:00:00Z",
  "to_date": "2026-03-15T15:00:00Z",
  "service_name": "Deep Tissue Massage",
  "cancel_deadline": 24,
  "formatted_location": "123 Wellness St, Suite 200, San Francisco, CA 94102",
  "price": {
    "amount": 8500,
    "currency": "USD",
    "formatted": "$85.00"
  },
  "price_type": "per_person",
  "merchant_name": "Spa Retreat",
  "is_cancelled": false
}

​
Update Booking by Merchant

Merchants can update booking times and notes. 
curl -X PATCH https://api.example.com/bookings/merchant/123 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_note": "Client requested room with natural light",
    "from_date": "2026-03-15T15:00:00Z",
    "to_date": "2026-03-15T16:00:00Z"
  }'

​
Request Parameters

​
merchant_note
string
required
Internal notes about the booking. Can be an empty string to clear notes.
​
from_date
string
required
New start date and time in ISO 8601 format (RFC3339)
​
to_date
string
required
New end date and time in ISO 8601 format (RFC3339)

​
Response

Returns 200 OK on success with no response body.
Time Validation: The system validates that the new time slot is available and doesn’t conflict with other bookings or employee schedules.

​
Cancel Booking by Customer

Customers can cancel their bookings before the cancellation deadline. 
curl -X DELETE https://api.example.com/bookings/customer/123 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "booking_id": 123,
    "merchant_name": "spa-retreat"
  }'

​
Request Parameters

​
booking_id
integer
required
ID of the booking to cancel
​
merchant_name
string
required
Unique identifier for the merchant

​
Response

Returns 200 OK on success with no response body.
Cancellation Deadline: The API enforces the service’s cancellation deadline. Attempts to cancel after the deadline will result in an error.

​
Cancel Booking by Merchant

Merchants can cancel any booking with an optional reason. 
curl -X DELETE https://api.example.com/bookings/merchant/123 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_reason": "Employee called in sick, unable to provide service"
  }'

​
Request Parameters

​
cancellation_reason
string
Reason for cancellation. Can be empty string but field must be present.

​
Response

Returns 200 OK on success with no response body.
When a merchant cancels a booking, the cancelled_by_merchant_on timestamp is recorded along with the cancellation reason.

​
Get Calendar Events

Retrieve all bookings and blocked times for a merchant’s calendar view. 
curl -X GET "https://api.example.com/bookings/calendar/events?start=2026-03-01T00:00:00Z&end=2026-03-31T23:59:59Z" \
  -H "Authorization: Bearer TOKEN"

​
Query Parameters

​
start
string
required
Start of the date range in ISO 8601 format
​
end
string
required
End of the date range in ISO 8601 format

​
Response Fields

​
bookings
array
required
Array of booking details
​
bookings[].id
integer
required
Booking ID
​
bookings[].from_date
timestamp
required
Start date and time
​
bookings[].to_date
timestamp
required
End date and time
​
bookings[].customer_note
string
Note from the customer
​
bookings[].merchant_note
string
Internal merchant note
​
bookings[].service_name
string
required
Name of the service
​
bookings[].service_color
string
required
Color code for calendar display
​
bookings[].service_duration
integer
required
Duration in minutes
​
bookings[].price
FormattedPrice
required
Price information
​
bookings[].cost
FormattedPrice
required
Cost to merchant
​
bookings[].first_name
string
Customer’s first name
​
bookings[].last_name
string
Customer’s last name
​
bookings[].phone_number
string
Customer’s phone number
​
blocked_times
array
required
Array of blocked time periods
​
blocked_times[].id
integer
required
Blocked time ID
​
blocked_times[].employee_id
integer
required
Employee this block applies to
​
blocked_times[].name
string
required
Name/description of the blocked time
​
blocked_times[].from_date
timestamp
required
Start of blocked period
​
blocked_times[].to_date
timestamp
required
End of blocked period
​
blocked_times[].all_day
boolean
required
Whether this is an all-day block
​
blocked_times[].icon
string
Icon identifier for display
​
blocked_times[].blocked_type_id
integer
Category ID for the blocked time

​
Example Response

{
  "bookings": [
    {
      "id": 123,
      "from_date": "2026-03-15T14:00:00Z",
      "to_date": "2026-03-15T15:00:00Z",
      "customer_note": "First time client",
      "merchant_note": "Prefers quiet environment",
      "service_name": "Deep Tissue Massage",
      "service_color": "#4F46E5",
      "service_duration": 60,
      "price": {
        "amount": 8500,
        "currency": "USD",
        "formatted": "$85.00"
      },
      "cost": {
        "amount": 3000,
        "currency": "USD",
        "formatted": "$30.00"
      },
      "first_name": "Jane",
      "last_name": "Smith",
      "phone_number": "+1234567890"
    }
  ],
  "blocked_times": [
    {
      "id": 456,
      "employee_id": 789,
      "name": "Lunch Break",
      "from_date": "2026-03-15T12:00:00Z",
      "to_date": "2026-03-15T13:00:00Z",
      "all_day": false,
      "icon": "utensils",
      "blocked_type_id": 1
    }
  ]
}
Calendar Integration: This endpoint is designed to provide all the data needed for a visual calendar interface, combining both bookings and unavailable time periods.

​
Error Responses

Status CodeDescription
400 Bad RequestInvalid parameters or validation error
401 UnauthorizedMissing or invalid authentication token
403 ForbiddenNot authorized to access or modify this booking
404 Not FoundBooking not found
409 ConflictCannot cancel (past deadline or already cancelled)

​
Managing Participants

For group bookings, participants are managed automatically:
  • Adding Participants: Customers join by creating a booking with the booking_id parameter
  • Removing Participants: Customers cancel their participation using the cancel endpoint
  • Current Count: The current_participants field tracks the number of active participants
  • Capacity Limits: Bookings enforce min_participants and max_participants constraints
Minimum Participants: If a group booking falls below the minimum participant count after cancellations, the merchant may need to cancel the entire booking.

Build docs developers (and LLMs) love

Get started for freeTalk to us