Skip to main content

​
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 -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