Working with Appointments

Overview

Appointments are the core of Bronjoy. This guide covers the staff/owner perspective — creating, reviewing, updating, and managing appointments throughout their lifecycle.

For the client-side booking flow, see Booking Flow.

Appointment Status Flow

Draft → Pending → Confirmed → Completed
                     ↓            ↓
                  Cancelled    NoShow

Creating Appointments (Staff)

Staff can create appointments on behalf of clients:

POST /api/org/appointments
Authorization: Bearer your-token
Content-Type: application/json

{
  "client_id": 42,
  "service_id": 1,
  "staff_id": 3,
  "branch_id": 1,
  "start_time": "2026-04-01T10:00:00Z",
  "notes": "Regular client, prefers extra pressure"
}

Tips:

• Always set notes for clients with specific preferences or medical considerations
• If the client doesn't exist yet, create them first via POST /api/org/clients
• Staff-created appointments start as Confirmed by default (bypassing payment)

Listing Appointments

All appointments

GET /api/org/appointments
Authorization: Bearer your-token

Filter by date range, status, or staff:

GET /api/org/appointments?start_date=2026-04-01&end_date=2026-04-30&status=Confirmed&staff_id=3

Pending appointments

View appointments awaiting action (confirmation, payment):

GET /api/org/appointments/pending

Review this list regularly — pending appointments that linger may mean payment issues or forgotten confirmations.

Calendar view

GET /api/org/appointments/calendar?start=2026-04-01&end=2026-04-30

Returns a structured view suitable for calendar rendering. Use this endpoint to power your dashboard calendar.

Updating an Appointment

PUT /api/org/appointments/{appointment}
Content-Type: application/json

{
  "notes": "Updated preference: light pressure only",
  "staff_id": 4
}

You can update most fields on an appointment as long as it hasn't been completed or cancelled.

Status Transitions

Confirm an appointment

Manually confirm a pending appointment (e.g., payment received offline):

POST /api/org/appointments/{appointment}/submit

Cancel

POST /api/org/appointments/{appointment}/cancel
Content-Type: application/json

{
  "reason": "Staff unavailable due to illness"
}

When you cancel, the client receives a notification. If payment was collected, initiate a refund separately (see Payments).

Reschedule

POST /api/org/appointments/{appointment}/reschedule
Content-Type: application/json

{
  "start_time": "2026-04-02T11:00:00Z",
  "staff_id": 3
}

The client is notified of the new time.

Batch Operations

Efficiently manage multiple appointments at once:

Batch update

POST /api/org/appointments/batch-update
Content-Type: application/json

{
  "ids": [101, 102, 103],
  "data": { "status": "Completed" }
}

Useful for marking end-of-day appointments as completed.

Batch delete

POST /api/org/appointments/batch-destroy
Content-Type: application/json

{
  "ids": [104, 105]
}

Prefer cancellation over deletion. Deleted appointments don't appear in history or reports.

Client Notes

Attach internal notes to a client's profile — these are visible to staff but not clients:

POST /api/org/clients/{client}/notes
Content-Type: application/json

{
  "note": "Allergic to certain hair dyes. Always check before service."
}

Notes appear whenever viewing the client's appointment, helping staff prepare.

Best Practices

Daily workflow

1. Morning — Review today's appointments in the calendar view. Check for any Pending appointments that need confirmation.
2. During the day — Mark appointments as Completed after the service is delivered.
3. End of day — Use batch update to complete all remaining appointments from the day.

Handling no-shows

If a client doesn't show up, mark the appointment as NoShow rather than cancelling. This preserves your no-show data and helps you identify patterns.

No-show appointments don't count as cancellations and won't trigger refund logic.

Overbooking prevention

The slot calculator prevents double-booking automatically. However:

• If you manually create appointments, be careful with the start_time — it won't be checked against existing bookings in manual creation flows
• Always check the calendar before creating a manual appointment at a specific time

Last-minute cancellations

Configure cancellation_hours in your settings to control how far in advance clients can cancel. After that window, clients can still request a cancellation, but staff must process it manually.

Reports and Analytics

GET /api/org/dashboard

The dashboard returns key metrics including:

• Today's appointment count
• Upcoming appointments this week
• Revenue summary
• Recent cancellations and no-shows

For detailed transaction reports:

GET /api/org/transactions
GET /api/org/transactions/summary
GET /api/org/transactions/export