Create an appointment
Create a new appointment as a client.
Optional tip, payment selection, booking message, and portfolio photos are accepted at create so they are not discarded when the booking is still pending barber approval. Tips are recorded as booking intent and are not charged at create; authorization holds use the appointment cost excluding tip. Platform authorization uses the selected saved payment method, a completed customer-bound setup, or the customer’s default saved method in that order. A completed appointment-scoped setup, including one completed with Apple Pay or another supported digital wallet, satisfies a card-required booking. A newly collected method is reusable or made default only with explicit consent.
When the governing client group requires a card deposit, Guile calculates it from the server-resolved service subtotal and captures it before publishing an immediately confirmed appointment. The deposit excludes tips, taxes, Guile fees, processing fees, and off-hours fees. Approval-pending appointments preserve the calculated deposit and defer capture until confirmation.
Revalidates availability, price, service eligibility, and confirmation policy before creating the appointment. A regular opening offer binds the exact occurrence selected by the customer, including its time zone. Off-hours appointments require barber approval and consume the requested capacity while pending.
Malformed, tampered, expired, and authority-stale regular opening
offers return malformedAppointmentOpeningOffer,
invalidAppointmentOpeningOffer, appointmentOpeningOfferExpired,
and appointmentOpeningOfferStale, respectively.
An off-hours quote may be redeemed once. Repeating a successful request
with the same idempotency key returns the original appointment. Reusing
the quote with another key returns offHoursQuoteAlreadyUsed; a
different quote or actor losing the same-slot race returns
appointmentSlotUnavailable.
Missing, malformed, tampered, expired, and policy-stale quotes return
offHoursQuoteRequired, malformedOffHoursQuote,
invalidOffHoursQuote, offHoursQuoteExpired, and
offHoursQuoteStale, respectively. Fee drift returns priceChanged;
service eligibility drift returns serviceNotAvailableForOffHours.
Selected service IDs must be visible in the booked barber’s current
public catalog. Create derives cost and duration from that catalog.
Optional client cost or duration values are freshness checks only; a
mismatch returns serviceTermsChanged. Hidden, foreign, or missing
services return serviceNotBookable.
Headers
Body
Request body for creating an appointment as a client.
Tip, payment selection, booking message, and barber portfolio photos are optional V1 booking inputs. Tips apply to both immediately confirmed appointments and pending booking requests. Customer photo upload is not part of this contract; only approved photos already present in the booked barber's public portfolio can be referenced.
The barber for this appointment.
The location for this appointment.
The services for this appointment.
The given name of the customer.
1 - 55The surname of the customer, if known.
1 - 55The tip the customer selected at booking time. Recorded on the appointment for barber visibility, including while the booking is still pending approval. Not charged at create; authorization holds exclude tip.
^(0|[1-9][0-9]*)\.[0-9][0-9]$"456.78"
The ISO 4217 currency code for
tipAmount, required when a tip is included.
3"USD"
How this appointment will be paid. Defaults to platform when omitted.
Only platform payments can be authorized through Guile; external payments,
such as cash or peer-to-peer payments, cannot. When this is external,
paymentMethodId, paymentMethodSetupId, and
setPaymentMethodAsDefault are not accepted.
platform, external The customer's payment method to authorize when paymentMethodSource is
platform or omitted. This must be a reusable method belonging to the
authenticated customer. It is mutually exclusive with
paymentMethodSetupId. When both are omitted and authorization is
required, the server uses the customer's default saved method.
setPaymentMethodAsDefault is not accepted with this field because the
method is already saved.
A completed payment-method setup created for the authenticated customer.
It is mutually exclusive with paymentMethodId and can be bound to only
one appointment. It is accepted only for a platform payment. The setup
owns the customer's reuse consent; appointment creation cannot broaden it.
Whether a newly collected reusable method becomes the customer's default.
Requires paymentMethodSetupId whose setup consent allows reuse.
Optional message for the barber saved with the booking.
150Optional approved photo identifiers from the booked barber's public portfolio. Customer uploads are deferred and are not accepted here.
1 - 3 elementsThe unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.
The exact regular opening offer selected for this appointment. Booking
clients that consume regularOffers echo it back; legacy regular
clients may omit it. It is mutually exclusive with quoteId. The
server revalidates its barber, location, services, occurrence, time
zone, schedule, booking window, service terms, authority revision, and
expiry before creation.
1 - 2048The off-hours quote selected for this appointment. Required when
creating an off-hours appointment and omitted for regular openings.
It is mutually exclusive with openingOfferId.
The quote is revalidated against the barber, location, selected
services, occurrence, time zone, opening band, fee, approval policy,
internal policy revision, and expiry before creation.
1 - 2048Response
Created.
A representation of an appointment.
The given name of the customer.
1 - 55The services for this appointment.
The duration of the appointment. The value is an ISO 8601 duration string.
For example, an appointment lasting 30 minutes would be represented as
PT30M.
The cost of the appointment, excluding any tips, fees or taxes.
^-?(0|[1-9][0-9]*)\.[0-9][0-9]$"456.78"
The barber for this appointment.
The location for this appointment.
The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.
The appointment state. This is derived and immutable.
pending, scheduled, canceled, completed, rejected, expired The payment state of the appointment. This is derived and immutable.
pending, processing, authorized, paid, failed The sum amount of authorized payments for this appointment.
^-?(0|[1-9][0-9]*)\.[0-9][0-9]$"456.78"
The sum amount of captured payments for this appointment.
^-?(0|[1-9][0-9]*)\.[0-9][0-9]$"456.78"
The sum amount of refunded payments for this appointment.
^-?(0|[1-9][0-9]*)\.[0-9][0-9]$"456.78"
The payment source for this appointment. Only platform payments can be authorized through Guile; external payments, such as cash or peer-to-peer payments, cannot.
platform, external Why this appointment is pending. bookingApproval means the customer
is waiting for the barber's decision. cardConfirmation means the
appointment is not awaiting booking approval but still needs card
confirmation. Absent when the appointment is not pending or when an
older server has not classified the pending state.
bookingApproval, cardConfirmation The immutable request lifecycle when this appointment originated as a booking request. Present while the request is pending and after it is resolved so the barber and customer can render the same outcome.
The off-hours fee accepted when the appointment was created. This is
derived and immutable. It is separate from cost. Creating the
appointment does not authorize or capture this fee; Guile settles it
only after the barber confirms the appointment.
^-?(0|[1-9][0-9]*)\.[0-9][0-9]$"456.78"
The opening band accepted when the appointment was created. This is derived and immutable.
regular, beforeHours, afterHours The tip the customer selected at booking time, when one was included. Not charged until capture.
^-?(0|[1-9][0-9]*)\.[0-9][0-9]$"456.78"
The customer's full surname when the authenticated barber may see it.
1 - 55The customer name the authenticated barber may display under the customer's surname visibility preference.
The IANA time zone for the appointment occurrence.
The identifier of the recurring appointment this appointment belongs to, if any. This field is only present for appointments that are part of a recurring series.
If included, the type of cancelation fee incurred. This is derived and immutable.
lateCancelation, noShow If included, the payment-link send state for this appointment.
The customer message saved with the appointment. Visible only to the appointment's barber and customer.
500Immutable references captured from the booked barber's approved public portfolio at booking time. These remain displayable on the appointment if the barber later changes the public portfolio.
3The cancellation decision recorded when the appointment is canceled.
The fee amounts available before a cancellation decision.
The required deposit for this appointment. Percentage deposits exclude tips, taxes, Guile fees, processing fees, and off-hours fees.
The URL of the calendar event artifact for this appointment.
Present only when the authenticated actor is the appointment's
customer and state is scheduled. Pending, confirming, rejected,
expired, and canceled booking requests do not expose a calendar event.
1024Whether the appointment's customer has already submitted a review for this visit. Present for the owning customer; omitted for other audiences.
Whether the appointment's customer dismissed the review prompt for this visit. Present for the owning customer; omitted for other audiences. Dismissing the prompt does not create a review and does not block leaving a review later from appointment history.