API

Owner - Booking Management

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

Base path: /api/v1/admin/bookings

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 manage bookings, view calendars, and update booking statuses (confirm, decline, mark no-show).

GET `/api/v1/admin/bookings/calendar` — Calendar View

Auth: Protected (Authorization: Bearer <accessToken>) · branch-manager+
Used by: owner-booki-web-app · Role: owner, branch-manager
Description: Fetch bookings for a calendar month view with breakdown by date.

Request

Query Parameters (required):

startDate (string): Start of date range in YYYY-MM-DD format
endDate (string): End of date range in YYYY-MM-DD format

GET /api/v1/admin/bookings/calendar?startDate=2026-04-01&endDate=2026-04-30

Response (200 OK)

[
  {
    "_id": "69df0733ab436daa9cc2fb87",
    "finalBookingDate": "2026-04-20",
    "finalBookingTime": "14:30:00",
    "status": "pending",
    "createdAt": "2026-04-15T03:34:11.607Z",
    "packageName": "Manicure + Pedicure",
    "packageAmount": 350,
    "customerName": "John Smith",
    "customerEmail": "john@example.com",
    "customerPhone": "09161234567",
    "statusLabel": "Pending"
  }
]

cURL Example

curl -X GET "http://localhost:4001/api/v1/admin/bookings/calendar?startDate=2026-04-01&endDate=2026-04-30" \
  -H "Authorization: Bearer OWNER_TOKEN"

GET `/api/v1/admin/bookings/date/:date/period/:period` — Bookings by Date & Period

Request

GET /api/v1/admin/bookings/date/2026-04-20/period/all

Path Parameters:

date (string): Date in YYYY-MM-DD format
period (string): am | pm | all

Query Parameters (optional):

page (number, default: 1)
limit (number, default: 10, max: 100)
sort (string, default: _id)
order (string, default: desc): asc | desc
status (string): Filter by booking status (see status values below)
packageId (string): Filter by package ID

Response (200 OK)

{
  "items": [
    {
      "bookingTimeCount": 1,
      "customers": [
        {
          "_id": "69df07f2579debdcb74d4118",
          "packageId": "69de52cd4f3e4272e30c7a18",
          "finalBookingDate": "2026-04-20",
          "finalBookingTime": "12:30:00",
          "status": "pending",
          "createdAt": "2026-04-15T03:37:22.215Z",
          "packageName": "Gel Nail Package",
          "packageAmount": 600,
          "customerName": "John Smith",
          "customerEmail": "john@example.com",
          "customerPhone": "09161234567",
          "statusLabel": "Pending",
          "initialBookingDate": "2026-04-20",
          "initialBookingTime": "12:30:00"
        }
      ],
      "bookingTime": "12:30:00"
    },
    {
      "bookingTimeCount": 3,
      "customers": [
        {
          "_id": "69defc2e27e1a548fd0cce1c",
          "packageId": "69de52bc4f3e4272e30c7a15",
          "finalBookingDate": "2026-04-20",
          "finalBookingTime": "14:30:00",
          "status": "pending",
          "createdAt": "2026-04-15T02:47:10.384Z",
          "packageName": "Hair Coloring Package",
          "packageAmount": 1500,
          "customerName": "John Smith",
          "customerEmail": "john@example.com",
          "customerPhone": "09161234567",
          "statusLabel": "Pending",
          "initialBookingDate": "2026-04-20",
          "initialBookingTime": "14:30:00"
        },
        {
          "_id": "69df045327e1a548fd0cce1e",
          "packageId": "69de52c14f3e4272e30c7a16",
          "finalBookingDate": "2026-04-20",
          "finalBookingTime": "14:30:00",
          "status": "pending",
          "createdAt": "2026-04-15T03:21:55.945Z",
          "packageName": "Rebond + Treatment",
          "packageAmount": 2500,
          "customerName": "John Smith",
          "customerEmail": "john@example.com",
          "customerPhone": "09161234567",
          "statusLabel": "Pending",
          "initialBookingDate": "2026-04-20",
          "initialBookingTime": "14:30:00"
        },
        {
          "_id": "69df0733ab436daa9cc2fb87",
          "packageId": "69de52c84f3e4272e30c7a17",
          "finalBookingDate": "2026-04-20",
          "finalBookingTime": "14:30:00",
          "status": "pending",
          "createdAt": "2026-04-15T03:34:11.607Z",
          "packageName": "Manicure + Pedicure",
          "packageAmount": 350,
          "customerName": "John Smith",
          "customerEmail": "john@example.com",
          "customerPhone": "09161234567",
          "statusLabel": "Pending",
          "initialBookingDate": "2026-04-20",
          "initialBookingTime": "14:30:00"
        }
      ],
      "bookingTime": "14:30:00"
    }
  ],
  "pages": 1,
  "pageRange": "1-2 of 2"
}

cURL Example

curl -X GET "http://localhost:4001/api/v1/admin/bookings/date/2026-04-20/period/all" \
  -H "Authorization: Bearer OWNER_TOKEN"

GET `/api/v1/admin/bookings/reschedule` — List Pending Reschedule Requests

Auth: Protected (Authorization: Bearer <accessToken>) · branch-manager+
Used by: owner-booki-web-app · Role: owner, branch-manager
Description: Retrieve all bookings with pending-reschedule status — customer requests that the owner needs to review and act on.

Request

GET /api/v1/admin/bookings/reschedule

Query Parameters (optional):

page (number, default: 1)
limit (number, default: 10, max: 100)
sort (string, default: _id)
order (string, default: desc): asc | desc
search (string): Search term

Response (200 OK)

{
  "items": [
    {
      "customerName": "John Smith",
      "packageName": "Basic Haircut",
      "initialBookingDate": "2026-04-08",
      "initialBookingTime": "09:30",
      "rescheduleBookingDate": "2026-04-12",
      "rescheduleBookingTime": "14:00",
      "status": "pending-reschedule",
      "statusLabel": "Pending Reschedule"
    }
  ],
  "pages": 1,
  "pageRange": "1-1 of 1"
}

cURL Example

curl -X GET "http://localhost:4001/api/v1/admin/bookings/reschedule" \
  -H "Authorization: Bearer OWNER_TOKEN"

PUT `/api/v1/admin/bookings/:id/confirm` — Confirm Booking

Auth: Protected (Authorization: Bearer <accessToken>) · branch-manager+
Used by: owner-booki-web-app · Role: owner, branch-manager
Description: Confirm a pending booking.

Request

PUT /api/v1/admin/bookings/507f191e810c19729de860ea/confirm

No request body required.

Response (200 OK)

Response message depends on the booking's current status:

{ "message": "Booking has been confirmed successfully." }

{ "message": "Rescheduled booking has been confirmed successfully." }

{ "message": "Cancellation request has been confirmed successfully." }

Error Responses

400 Bad Request — Booking already confirmed:

{
  "statusCode": 400,
  "message": "This booking is already confirmed."
}

400 Bad Request — Invalid status transition:

{
  "statusCode": 400,
  "message": "Invalid booking status. This booking can no longer be confirmed."
}

cURL Example

curl -X PUT http://localhost:4001/api/v1/admin/bookings/507f191e810c19729de860ea/confirm \
  -H "Authorization: Bearer OWNER_TOKEN"

PUT `/api/v1/admin/bookings/:id/decline` — Decline Booking

Request

PUT /api/v1/admin/bookings/507f191e810c19729de860ea/decline

Optional body:

{
  "declineReason": "Schedule conflict"
}

Fields:

declineReason (string, optional): Reason for declining (shown to customer)

Response (200 OK)

Response message depends on the booking's current status:

{ "message": "Booking has been declined successfully." }

{ "message": "Reschedule request has been declined successfully." }

{ "message": "Cancellation request has been declined successfully." }

Error Responses

400 Bad Request — Invalid status transition:

{
  "statusCode": 400,
  "message": "Invalid booking status. This booking can no longer be declined."
}

cURL Example

curl -X PUT http://localhost:4001/api/v1/admin/bookings/507f191e810c19729de860ea/decline \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OWNER_TOKEN" \
  -d '{
    "declineReason": "Schedule conflict"
  }'

PUT `/api/v1/admin/bookings/:id/no-show` — Mark as No-Show

Auth: Protected (Authorization: Bearer <accessToken>) · branch-manager+
Used by: owner-booki-web-app · Role: owner, branch-manager
Description: Mark a confirmed booking as "no-show" (customer didn't arrive).

Request

PUT /api/v1/admin/bookings/507f191e810c19729de860ea/no-show

No request body required.

Only valid for bookings with paid or ongoing status.

Response (200 OK)

{
  "message": "Booking has been marked as no show successfully."
}

Error Responses

400 Bad Request — Invalid status:

{
  "statusCode": 400,
  "message": "Invalid booking status. This booking can no longer be marked as no show."
}

cURL Example

curl -X PUT http://localhost:4001/api/v1/admin/bookings/507f191e810c19729de860ea/no-show \
  -H "Authorization: Bearer OWNER_TOKEN"

Booking Status Lifecycle

Status	Description
`pending-verification`	Awaiting email/OTP verification
`verified`	Booking verified (payment or manual)
`pending`	Awaiting owner confirmation
`confirmed`	Owner approved
`declined`	Owner rejected (customer notified)
`pending-reschedule`	Customer reschedule request awaiting owner review
`confirmed-reschedule`	Owner approved the reschedule
`declined-reschedule`	Owner rejected the reschedule
`rescheduled`	Moved to a new date/time
`pending-cancel`	Customer cancel request awaiting owner review
`confirmed-cancel`	Owner approved the cancellation
`declined-cancel`	Owner rejected the cancellation
`cancelled`	Booking cancelled by customer
`cancelled-admin`	Booking cancelled by admin
`paid`	Payment received
`ongoing`	Service in progress
`completed`	Service completed successfully
`no-show`	Customer did not arrive
`unpaid-expired`	Booking expired due to non-payment
`expired`	Booking expired without action

Booking Fields

Field	Type	Description
`bookingId`	ObjectId	Unique booking identifier
`bookingDate`	string	Date (YYYY-MM-DD)
`bookingTime`	string	Time (HH:MM)
`customerName`	string	First + last name
`customerEmail`	string	Email address
`customerPhone`	string	Phone number
`packageName`	string	Service package booked
`status`	string	Current booking status
`amount`	number	Price in PHP
`notes`	string	Internal notes

Notes

All owner endpoints require owner or branch_manager role.
Calendars are timezone-aware; ensure correct timezone in organizational settings.
Declined/no-show bookings trigger customer email notifications.
Rescheduling requires owner approval to avoid double-bookings.

Maya Payments

Maya payment endpoints: checkout sessions, webhooks, and subscription flows.

Owner - Customer Management

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