Manage appointments and recurring appointments for barbers and customers on Guile
The Appointments API enables customers to book appointments with barbers and allows barbers to manage their schedules. The platform supports both one-time appointments and recurring appointment series.
Customers can create appointments by selecting a barber, location, services, and time slot. Barbers can also create appointments on behalf of customers with full control over cost and duration.All appointment creation operations require an idempotency key to prevent duplicate bookings. The system validates availability, checks for scheduling conflicts, and confirms the appointment details before creation.
Recurring appointments allow barbers to set up automatic appointment creation for regular customers. Each customer is limited to one recurring appointment per barber to maintain scheduling clarity.When you create a recurring appointment, you specify:
Frequency: How often appointments recur (daily, weekly, biweekly, semimonthly, monthly, quarterly, or annually)
Start Date: When the recurring series begins
End Date (optional): When the series ends. If not specified, appointments are created up to one year from the start date or current date, whichever is later
Active Status: Whether new appointments should continue to be created
Recurring appointments are created in the background by the system based on the specified frequency and date range. These appointments are not automatically confirmed - they require confirmation from the customer or barber.
You can update a recurring appointment to change the frequency, dates, or active status. When you deactivate a recurring appointment, no new appointments will be created, but existing appointments remain scheduled.When deleting a recurring appointment, you must specify an earliestDeletionDate in the future. Appointments scheduled before this date are preserved, while appointments on or after this date are deleted. This allows you to stop future appointments while keeping past and near-term appointments intact.
When you delete an individual appointment that belongs to a recurring series, only that specific instance is deleted. The recurring appointment continues to create future appointments according to its schedule.
Appointments support multiple payment methods including credit cards, debit cards, and external payments (cash or peer-to-peer systems like Venmo). Payments can be authorized at booking time and captured later, or processed immediately.Barbers can capture authorized payments when services are completed. If needed, payments can be refunded with optional reason codes.
Both customers and barbers can cancel appointments. When a barber cancels an appointment, they can optionally apply cancellation fees for late cancellations or no-shows, depending on the timing and circumstances.
Always use idempotency keys when creating appointments or recurring appointments to prevent duplicate bookings. Check appointment openings before creating appointments to ensure availability.For recurring appointments, consider the customer’s schedule and preferences when setting the frequency. Monitor inactive recurring appointments and clean them up periodically to maintain data hygiene.When deleting recurring appointments, carefully choose the earliestDeletionDate to preserve appointments that customers may have already planned around while removing unwanted future appointments.
