Skip to main content
Use the Appointments API when a customer books with a barber, or when a barber books on a customer’s behalf. You can create one-time appointments and recurring series.

​
What you do first

  1. Check appointment openings so you know the slot is free.
  2. Create an appointment as the customer, or create as a barber with cost and duration.
  3. Send an idempotency key on every create so a same-key retry can replay the first result instead of starting a second booking.
  4. For a series, create a recurring appointment with frequency, start date, optional end date, and active status.
Each customer gets at most one recurring series per barber. Guile creates future visits in the background from the frequency and date range, they are not confirmed for you; the customer or barber still confirms each one. Without an end date, Guile creates appointments up to one year from the start date or today, whichever is later.

​
States that matter

Update a recurring appointment to change frequency, dates, or active status. Deactivate it and no new appointments are created; ones already on the calendar stay. When you delete a series, send an earliestDeletionDate in the future so near-term visits stay. Delete a single visit and only that appointment goes away. List appointments with date ranges, payment states, payment methods, payment directions, and appointment states. List recurring appointments for a barber and filter by customer.

​
When a call fails

Failures come back as problem documents. Open the type link for the cause, the fix, and whether retrying is safe. Always send idempotency keys on creates. When you delete a series, pick earliestDeletionDate so visits people already planned around stay put. Customers and barbers can cancel. When a barber cancels, they can apply cancellation fees for late cancels or no-shows when the timing allows it.
  • Appointments accept cards and external payments (cash or peer-to-peer tools like Venmo). Authorize an appointment payment at booking and capture later, or charge immediately, capture when the service is done; refund with an optional reason code.
  • Card-present collection lives under Payments.
  • Refund requests live under Refunds.
  • Date ranges: filter list calls by day.