Public Bookings API

Public endpoint for creating service bookings

Public Bookings API

The Public Bookings API allows authenticated users to create bookings for active services. Unlike the admin bookings API, this is the customer-facing endpoint.

Authentication

Requires valid user session (any authenticated user can create bookings).

Authorization: Bearer <session-token>

Create booking

Create a new booking for a service.

Endpoint: POST /api/services/bookings

cURL

curl -X POST https://your-domain.com/api/services/bookings \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "service-uuid",
    "bookingDate": "2024-12-15",
    "bookingTime": "14:00",
    "customerMessage": "Looking forward to this service!"
  }'

Request Body:

serviceId · string · required

UUID of the service to book

bookingDate · string · required

Date in YYYY-MM-DD format

bookingTime · string · required

Time in HH:MM format (24-hour)

customerMessage · text

Optional message from customer to provider

Validation & business logic

The endpoint performs comprehensive validation:

1. Service validation

• Service must exist
• Service status must be "active"
• Provider (owner) must exist

2. Availability check

• Converts bookingDate to day of week (0-6)
• Queries servicesAvailability table for matching slots
• Verifies bookingTime falls within an available slot
• Checks isAvailable = true for the slot

3. Conflict detection

• Queries existing bookings for the same service, date, and time
• Rejects if another booking exists (no double-booking)

4. Automatic calculations

• Total price: Uses service’s basePrice
• Currency: Uses service’s currency
• Duration: Uses service’s durationMinutes
• Booking end time: Calculated as bookingTime + durationMinutes

Response

id · string

Booking UUID

serviceId · string

Service UUID

providerId · string

Provider (service owner) user ID

customerId · string

Customer (current user) ID

bookingDate · string

Booking date (YYYY-MM-DD)

bookingTime · string

Start time (HH:MM)

bookingEndTime · string

Calculated end time (HH:MM)

durationMinutes · number

Service duration

totalPrice · number

Price in minor currency units (e.g., cents)

currency · string

Currency code (e.g., “EUR”)

status · string

Always "pending" for new bookings

customerMessage · text

Customer’s message (if provided)

createdAt · timestamp

Booking creation timestamp

Example response:

{
  "id": "booking-uuid",
  "serviceId": "service-uuid",
  "providerId": "provider-user-id",
  "customerId": "customer-user-id",
  "bookingDate": "2024-12-15",
  "bookingTime": "14:00",
  "bookingEndTime": "15:30",
  "durationMinutes": 90,
  "totalPrice": 5000,
  "currency": "EUR",
  "status": "pending",
  "customerMessage": "Looking forward to this service!",
  "createdAt": "2024-12-01T10:30:00Z"
}

Error responses

Authentication required

{
  "error": "Authentification requise"
}

Status: 401

Invalid JSON

{
  "error": "JSON invalide"
}

Status: 400

Missing required fields

{
  "error": "serviceId, bookingDate et bookingTime sont requis"
}

Status: 400

Service not found

{
  "error": "Service introuvable"
}

Status: 404

Service not active

{
  "error": "Ce service n'est pas disponible"
}

Status: 400

Time slot not available

{
  "error": "Aucun créneau disponible pour ce jour et cette heure"
}

Status: 400

Booking conflict

{
  "error": "Ce créneau est déjà réservé"
}

Status: 409

Booking workflow

1. Customer submits booking → Status: pending
2. Provider reviews (via admin API)
3. Provider confirms → Status: confirmed
4. Service delivered → Status: completed

Alternative flows:

• Provider can cancel or reject bookings
• Customer no-show → Status: no_show

The booking status can only be changed by the provider through the admin API (/api/admin/services/bookings). Customers cannot cancel or modify bookings through this endpoint.

Day of week calculation

The availability system uses JavaScript’s Date.getDay():

• 0 = Sunday
• 1 = Monday
• 2 = Tuesday
• 3 = Wednesday
• 4 = Thursday
• 5 = Friday
• 6 = Saturday

Example: 2024-12-15 (Sunday) → dayOfWeek = 0

Time slot matching

A booking time is valid if:

bookingTime >= slot.startTime && bookingTime <= slot.endTime

Example:

• Slot: 09:00 - 17:00
• Booking time 14:00 → Valid ✓
• Booking time 18:00 → Invalid ✗

Implementation reference

Source: /src/pages/api/services/bookings.ts

Key implementation details:

• Session extraction from locals.session or locals.user
• Drizzle ORM queries for validation
• Date/time calculations using JavaScript Date
• Conflict detection with eq() and and() operators
• Automatic field population from service data

Timezone Note: The current implementation does not handle timezone conversions. All times are treated as local to the application server. Consider adding timezone support for multi-region deployments.

See also

• Bookings Feature Guide
• Services API (Admin)
• Availability Management
• Database Schema