Bookings API

API for managing all bookings

GET /bookings

Get all bookings

Query Parameters

Parameter	Type	Description	Default
page	number	Current page	1
limit	number	Items per page	20
status	string	Filter by status	-
from	string	Start date (ISO 8601)	-
to	string	End date (ISO 8601)	-
customerId	string	Filter by customer	-
serviceId	string	Filter by service	-
staffId	string	Filter by staff	-

Status Values

Status	Description
pending	Pending confirmation
confirmed	Confirmed
completed	Completed
cancelled	Cancelled
no_show	No show

Response

{
  "success": true,
  "data": [
    {
      "id": "bk_123456",
      "customer": {
        "id": "cust_123",
        "name": "John Doe",
        "email": "john@email.com",
        "phone": "081-234-5678"
      },
      "service": {
        "id": "svc_456",
        "name": "Haircut",
        "duration": 60,
        "price": 300
      },
      "staff": {
        "id": "staff_789",
        "name": "Daeng"
      },
      "dateTime": "2024-01-15T10:00:00Z",
      "endTime": "2024-01-15T11:00:00Z",
      "status": "confirmed",
      "notes": "Special appointment request",
      "createdAt": "2024-01-10T08:30:00Z",
      "updatedAt": "2024-01-10T08:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

---

GET /bookings/:id

Get booking details by ID

Path Parameters

Parameter	Type	Description
id	string	Booking ID (e.g., bk_123456)

Response

{
  "success": true,
  "data": {
    "id": "bk_123456",
    "customer": {
      "id": "cust_123",
      "name": "John Doe",
      "email": "john@email.com",
      "phone": "081-234-5678"
    },
    "service": {
      "id": "svc_456",
      "name": "Haircut",
      "duration": 60,
      "price": 300
    },
    "staff": {
      "id": "staff_789",
      "name": "Daeng"
    },
    "dateTime": "2024-01-15T10:00:00Z",
    "endTime": "2024-01-15T11:00:00Z",
    "status": "confirmed",
    "notes": "Special appointment request",
    "payment": {
      "status": "paid",
      "method": "card",
      "amount": 300,
      "paidAt": "2024-01-15T09:45:00Z"
    },
    "createdAt": "2024-01-10T08:30:00Z",
    "updatedAt": "2024-01-10T08:30:00Z"
  }
}

---

POST /bookings

Create a new booking

Request Body

{
  "customerId": "cust_123",
  "serviceId": "svc_456",
  "staffId": "staff_789",
  "dateTime": "2024-01-15T10:00:00Z",
  "notes": "Special appointment request",
  "source": "website"
}

Field	Type	Required	Description
customerId	string	✅	Customer ID
serviceId	string	✅	Service ID
staffId	string	✅	Staff ID
dateTime	string	✅	Desired date and time (ISO 8601)
notes	string	❌	Notes
source	string	❌	Source (website, app, walk-in)

Response

{
  "success": true,
  "data": {
    "id": "bk_789012",
    "customer": { ... },
    "service": { ... },
    "staff": { ... },
    "dateTime": "2024-01-15T10:00:00Z",
    "status": "pending",
    "createdAt": "2024-01-15T09:00:00Z"
  },
  "message": "Booking created successfully"
}

---

PATCH /bookings/:id

Update booking status or details

Request Body

{
  "status": "confirmed",
  "dateTime": "2024-01-15T11:00:00Z",
  "notes": "Updated notes"
}

Field	Type	Required	Description
status	string	❌	New status
dateTime	string	❌	New date and time
notes	string	❌	Notes

Response

{
  "success": true,
  "data": {
    "id": "bk_123456",
    "status": "confirmed",
    "updatedAt": "2024-01-15T09:30:00Z"
  },
  "message": "Booking updated successfully"
}

---

DELETE /bookings/:id

Cancel a booking

Query Parameters

Parameter	Type	Required	Description
reason	string	❌	Reason for cancellation
notifyCustomer	boolean	❌	Notify the customer (default: true)

Response

{
  "success": true,
  "data": {
    "id": "bk_123456",
    "status": "cancelled",
    "cancelledAt": "2024-01-15T09:30:00Z"
  },
  "message": "Booking cancelled successfully"
}

---

Example Code

Create a New Booking

async function createBooking(bookingData: {
  customerId: string;
  serviceId: string;
  staffId: string;
  dateTime: string;
}) {
  const response = await fetch('https://api.booking-platform.com/v1/bookings', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(bookingData),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  return response.json();
}

// Usage
const booking = await createBooking({
  customerId: 'cust_123',
  serviceId: 'svc_456',
  staffId: 'staff_789',
  dateTime: '2024-01-15T10:00:00Z',
});

Get Today's Bookings

async function getTodayBookings() {
  const today = new Date().toISOString().split('T')[0];
  
  const response = await fetch(
    `https://api.booking-platform.com/v1/bookings?from=${today}T00:00:00Z&to=${today}T23:59:59Z`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
      },
    }
  );

  const { data, pagination } = await response.json();
  return data;
}

Cancel a Booking

async function cancelBooking(bookingId: string, reason?: string) {
  const response = await fetch(
    `https://api.booking-platform.com/v1/bookings/${bookingId}?reason=${encodeURIComponent(reason || 'Customer cancelled')}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
      },
    }
  );

  return response.json();
}

---

Next Steps

• API Tester — Test API directly
• Authentication — How to authenticate