API

Owner - Customer Management

Owner endpoints for viewing customer profiles, booking history, and managing relationships.

Base path: /api/v1/owner/customers

Used by: owner-booki-web-app · Role: owner, branch-manager
organizationId: From authenticated user's JWT token (no tenant header needed)

Owner endpoints allow business owners to view customer information, booking history, preferences, and manage customer relationships.

GET `/api/v1/owner/customers` — List Customers

Request

Query Parameters (optional):

page (number, default: 1)
limit (number, default: 10, max: 100)
search (string): Search by name or email

GET /api/v1/owner/customers?page=1&limit=20&search=john

Response (200 OK)

{
  "items": [
    {
      "_id": "69def5f827e1a548fd0cce1a",
      "email": "john@example.com",
      "phone": "09161234567",
      "type": "customer",
      "name": "John Cruz Smith"
    }
  ],
  "pages": 1,
  "pageRange": "1-1 of 1"
}

cURL Example

curl -X GET "http://localhost:4001/api/v1/owner/customers?page=1&limit=20" \
  -H "Authorization: Bearer OWNER_TOKEN"

GET `/api/v1/owner/customers/:id` — Get Customer Profile

Auth: Protected (Authorization: Bearer <accessToken>) · branch-manager+
Used by: owner-booki-web-app · Role: owner, branch-manager
Description: Fetch the profile details of a single customer by their user ID.

Request

GET /api/v1/owner/customers/69def5f827e1a548fd0cce1a

Path Parameters:

id (string, required): Customer user ID (24-hex)

Response (200 OK)

{
  "_id": "69def5f827e1a548fd0cce1a",
  "email": "john@example.com",
  "phone": "09161234567",
  "type": "customer",
  "firstName": "John",
  "lastName": "Cruz Smith",
  "name": "John Cruz Smith",
  "organizationId": "507f191e810c19729de860ea",
  "status": "active",
  "createdAt": "2026-01-15T08:00:00Z"
}

cURL Example

curl -X GET http://localhost:4001/api/v1/owner/customers/69def5f827e1a548fd0cce1a \
  -H "Authorization: Bearer OWNER_TOKEN"

GET `/api/v1/owner/customers/:type/:id` — Get Customer Booking History

Auth: Protected (Authorization: Bearer <accessToken>) · branch-manager+
Used by: owner-booki-web-app · Role: owner, branch-manager
Description: Fetch booking history for a specific customer or guest. Use type=customer for registered users and type=guest for one-time guest bookings.

Request

GET /api/v1/owner/customers/customer/69def5f827e1a548fd0cce1a

Path Parameters:

type (string): customer | guest
id (string): Customer ID

Response (200 OK)

{
  "items": [
    {
      "_id": "69defc2e27e1a548fd0cce1c",
      "packageName": "Hair Coloring Package",
      "finalBookingDate": "2026-04-20",
      "finalBookingTime": "14:30:00",
      "status": "pending"
    },
    {
      "_id": "69df045327e1a548fd0cce1e",
      "packageName": "Rebond + Treatment",
      "finalBookingDate": "2026-04-20",
      "finalBookingTime": "14:30:00",
      "status": "pending"
    },
    {
      "_id": "69df0733ab436daa9cc2fb87",
      "packageName": "Manicure + Pedicure",
      "finalBookingDate": "2026-04-20",
      "finalBookingTime": "14:30:00",
      "status": "pending"
    },
    {
      "_id": "69df07f2579debdcb74d4118",
      "packageName": "Gel Nail Package",
      "finalBookingDate": "2026-04-20",
      "finalBookingTime": "12:30:00",
      "status": "confirmed"
    }
  ],
  "pages": 1,
  "pageRange": "1-4 of 4"
}

cURL Example

curl -X GET http://localhost:4001/api/v1/owner/customers/customer/69def5f827e1a548fd0cce1a \
  -H "Authorization: Bearer OWNER_TOKEN"

curl -X GET http://localhost:4001/api/v1/owner/customers/guest/69def5f827e1a548fd0cce1a \
  -H "Authorization: Bearer OWNER_TOKEN"

POST `/api/v1/owner/customers/:type/:id` — Create Booking Appointment

Auth: Protected (Authorization: Bearer <accessToken>) · branch-manager+
Used by: owner-booki-web-app · Role: owner, branch-manager
Description: Create a booking appointment on behalf of a specific customer or guest. Owners use this to manually schedule walk-in or phone-in appointments from the dashboard.

Request

POST /api/v1/owner/customers/customer/69def5f827e1a548fd0cce1a

Path Parameters:

type (string, required): customer | guest
id (string, required): Customer or guest user ID (24-hex)

{
  "packageId": "507f1f77bcf86cd799439031",
  "bookingDate": "2026-05-15",
  "bookingTime": "10:00",
  "preferredPaymentMethod": "cash"
}

Fields:

packageId (string, required): Service package ID (24-hex)
bookingDate (string, required): Appointment date in YYYY-MM-DD format (future)
bookingTime (string, required): Appointment time in HH:MM format (future)
preferredPaymentMethod (string, optional): cash | maya

Response (201 Created)

{
  "message": "Booking appointment created successfully.",
  "bookingId": "69defc2e27e1a548fd0cce1c"
}

Error Responses

400 Bad Request — Past date/time:

{
  "statusCode": 400,
  "message": "Please select a valid date for the booking. Past dates are not available."
}

cURL Example

curl -X POST "http://localhost:4001/api/v1/owner/customers/customer/69def5f827e1a548fd0cce1a" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OWNER_TOKEN" \
  -d '{
    "packageId": "507f1f77bcf86cd799439031",
    "bookingDate": "2026-05-15",
    "bookingTime": "10:00",
    "preferredPaymentMethod": "cash"
  }'

Owner - Booking Management

Owner dashboard endpoints for managing bookings, calendar views, and customer booking updates.

Stripe Payments

Stripe payment endpoints for booking payments, subscription intents, and webhook handling.