Bookings API

The Bookings API allows you to create, retrieve, update, and cancel appointments programmatically.

List Bookings

Retrieve a list of bookings with optional filters:

GET/api/bookings

// Example Response
{
  "data": [
    {
      "id": "bkg_abc123",
      "customer_id": "cus_xyz789",
      "service_id": "svc_456",
      "start_time": "2026-06-15T14:00:00Z",
      "end_time": "2026-06-15T15:00:00Z",
      "status": "confirmed",
      "price": 150.00,
      "created_at": "2026-06-10T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}

Create a Booking

Create a new appointment booking:

POST/api/bookings

// Request Body
{
  "customer_id": "cus_xyz789",
  "service_id": "svc_456",
  "start_time": "2026-06-15T14:00:00Z",
  "notes": "First-time consultation"
}

// Response
{
  "id": "bkg_abc123",
  "customer_id": "cus_xyz789",
  "service_id": "svc_456",
  "start_time": "2026-06-15T14:00:00Z",
  "end_time": "2026-06-15T15:00:00Z",
  "status": "confirmed",
  "price": 150.00,
  "created_at": "2026-06-10T10:30:00Z"
}

Get a Booking

GET/api/bookings/{id}

Cancel a Booking

DELETE/api/bookings/{id}

// Request Body (optional)
{
  "reason": "Customer requested cancellation",
  "notify_customer": true
}

// Response
{
  "id": "bkg_abc123",
  "status": "cancelled",
  "cancelled_at": "2026-06-10T11:00:00Z"
}

Query Parameters

Parameter	Type	Description
customer_id	string	Filter by customer
status	string	confirmed, cancelled, completed, no_show
date_from	ISO 8601	Start date filter
date_to	ISO 8601	End date filter
page	integer	Page number (default: 1)
per_page	integer	Results per page (max: 100)