Bookings API

The Bookings API allows you to programmatically create, retrieve, update, and manage service bookings.

Base URL

https://api.otesse.com/v1/bookings

List Bookings

GET /v1/bookings

Query Parameters

Parameter	Type	Description
status	string	Filter by status: confirmed, in_progress, completed, cancelled
customer_id	string	Filter by customer ID
zone_id	string	Filter by zone ID
date_from	string (ISO 8601)	Start of date range
date_to	string (ISO 8601)	End of date range
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 25, max: 100)

Example Request

curl -X GET "https://api.otesse.com/v1/bookings?status=confirmed&date_from=2026-02-01" \
  -H "Authorization: Bearer otesse_live_sk_..."

Example Response

{
  "data": [
    {
      "id": "bk_01HQ3K5M7N8P9R",
      "status": "confirmed",
      "customer": {
        "id": "cust_01HQ3K5M7N",
        "name": "John Smith",
        "email": "john@example.com"
      },
      "service": {
        "industry": "cleaning",
        "configuration": {
          "bedrooms": 3,
          "bathrooms": 2,
          "frequency": "bi-weekly"
        }
      },
      "scheduled_at": "2026-02-26T10:00:00Z",
      "estimated_duration": 120,
      "address": {
        "street": "123 Main St",
        "city": "Eugene",
        "state": "OR",
        "zip": "97401"
      },
      "pricing": {
        "subtotal": 15000,
        "tax": 1275,
        "discount": 0,
        "total": 16275
      },
      "assigned_crew": ["staff_01HQ3K5M"],
      "created_at": "2026-02-20T14:30:00Z",
      "updated_at": "2026-02-20T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 142,
    "total_pages": 6
  }
}

Note: All monetary amounts are in cents (e.g., 15000 = $150.00).

Create a Booking

POST /v1/bookings

Request Body

{
  "customer_id": "cust_01HQ3K5M7N",
  "industry": "cleaning",
  "configuration": {
    "bedrooms": 3,
    "bathrooms": 2,
    "frequency": "one-time",
    "extras": ["inside_oven", "inside_fridge"]
  },
  "scheduled_at": "2026-03-01T10:00:00Z",
  "address_id": "addr_01HQ3K5M7N",
  "notes": "Please use the back entrance. Gate code: 1234.",
  "coupon_code": "FIRST20"
}

Response

Returns the created booking object with a 201 Created status.

Get a Booking

GET /v1/bookings/:id

Returns the full booking object including status timeline, assigned crew details, and invoice references.

Update a Booking

PATCH /v1/bookings/:id

Updatable fields: scheduledat, configuration, notes, addressid. Status changes use dedicated endpoints.

Cancel a Booking

POST /v1/bookings/:id/cancel

{
  "reason": "Customer requested cancellation",
  "notify_customer": true
}

Returns the updated booking with status: "cancelled" and any applicable cancellation fee information.