> ## Documentation Index > Fetch the complete documentation index at: https://docs.guile.app/llms.txt > Use this file to discover all available pages before exploring further. # Confirm a booking request > Confirm an approval-pending booking request as the owning barber. Confirmation first claims the request so decline, customer cancellation, and expiry cannot process money concurrently. Guile then completes any required card authorization and off-hours fee settlement through a durable, provider-idempotent workflow before the appointment becomes scheduled. Preserved booking terms are not repriced. A completed workflow returns 200. A workflow that has safely claimed the request but still needs reconciliation returns 202 with `bookingRequest.state` set to `confirming`; clients poll the appointment rather than issuing another decision. Repeating the same request with the same idempotency key replays its original response. A new decision after the request was confirmed, rejected, expired, or canceled returns `appointmentApprovalNotPending`. Concurrent confirm, decline, customer cancellation, and expiry attempts produce exactly one terminal booking-request result. ## OpenAPI ````yaml /api-reference/Appointments/openapi.yaml post /barbers/{barberId}/appointments/{appointmentId}/confirmed openapi: 3.0.0 info: title: Appointments version: 0.1.0 contact: name: Guile Engineering url: https://www.guile.app email: engineering@guile.app license: name: MIT url: https://opensource.org/license/mit description: Appointment management servers: - url: https://api.guile.app variables: {} - url: https://guile.fly.dev variables: {} security: [] tags: - name: Recurring appointments description: Create and manage repeating visit series - name: Appointment management description: Barber-side confirm, decline, and cancel flows - name: Appointments description: Book, change, pay, and cancel visits paths: /barbers/{barberId}/appointments/{appointmentId}/confirmed: post: tags: - Appointments summary: Confirm a booking request description: |- Confirm an approval-pending booking request as the owning barber. Confirmation first claims the request so decline, customer cancellation, and expiry cannot process money concurrently. Guile then completes any required card authorization and off-hours fee settlement through a durable, provider-idempotent workflow before the appointment becomes scheduled. Preserved booking terms are not repriced. A completed workflow returns 200. A workflow that has safely claimed the request but still needs reconciliation returns 202 with `bookingRequest.state` set to `confirming`; clients poll the appointment rather than issuing another decision. Repeating the same request with the same idempotency key replays its original response. A new decision after the request was confirmed, rejected, expired, or canceled returns `appointmentApprovalNotPending`. Concurrent confirm, decline, customer cancellation, and expiry attempts produce exactly one terminal booking-request result. operationId: confirmBarberAppointmentRequest parameters: - $ref: '#/components/parameters/idempotencyKeyRequest' - name: barberId in: path required: true schema: $ref: '#/components/schemas/resourceId' - name: appointmentId in: path required: true schema: $ref: '#/components/schemas/resourceId' responses: '200': description: |- Ok. The operation succeeded. content: application/json: schema: $ref: '#/components/schemas/barberAppointmentDetail' example: appointment: id: 0190f0c0-4444-7444-8444-444444444444 givenName: Jordan barber: id: 0190f0c0-1111-7111-8111-111111111111 givenName: Marcus surname: Lee location: id: 0190f0c0-2222-7222-8222-222222222222 name: SoHo shopName: Guile Cuts services: - id: 0190f0c0-3333-7333-8333-333333333333 name: Haircut cost: '45.00' occursOn: '2026-08-15T15:30:00.000Z' duration: PT45M cost: '45.00' state: scheduled paymentState: pending totalAuthorized: '0.00' totalCaptured: '0.00' totalRefunded: '0.00' createdAt: '2026-08-01T16:00:00.000Z' updatedAt: '2026-08-01T16:00:00.000Z' '202': description: >- A confirmation request was accepted and is still reconciling. Poll the appointment until `bookingRequest.state` leaves `confirming`. content: application/json: schema: $ref: '#/components/schemas/barberAppointmentDetail' '400': description: >- Bad Request. The request body, request headers, and/or query parameters are not well-formed. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/badRequest](https://docs.guile.app/problems/badRequest) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '401': description: >- Unauthorized. The operation requires authentication but no authentication or insufficient authentication was given. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/unauthorized](https://docs.guile.app/problems/unauthorized) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '403': description: >- Forbidden. The authenticated caller is not authorized to perform the requested operation. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/forbidden](https://docs.guile.app/problems/forbidden) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '404': description: >- Not Found. There is no such resource at the request URL. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/notFound](https://docs.guile.app/problems/notFound) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '409': description: >- Conflict. The request conflicts with the state of the application. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/conflict](https://docs.guile.app/problems/conflict) * [https://docs.guile.app/problems/appointmentApprovalNotPending](https://docs.guile.app/problems/appointmentApprovalNotPending) * [https://docs.guile.app/problems/idempotencyKeyConflict](https://docs.guile.app/problems/idempotencyKeyConflict) * [https://docs.guile.app/problems/idempotencyRequestInProgress](https://docs.guile.app/problems/idempotencyRequestInProgress) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' example: id: 0190f0c0-cccc-7ccc-8ccc-cccccccccccc type: https://docs.guile.app/problems/appointmentApprovalNotPending title: Appointment Approval Not Pending status: 409 detail: Only pending requests can be confirmed. occurredAt: '2026-08-01T16:00:00.000Z' '422': description: >- Unprocessable Entity. The request body and/or query parameters were well-formed but otherwise invalid. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/unprocessableEntity](https://docs.guile.app/problems/unprocessableEntity) * [https://docs.guile.app/problems/appointmentConfirmationPaymentFailed](https://docs.guile.app/problems/appointmentConfirmationPaymentFailed) * [https://docs.guile.app/problems/paymentMethodNotSet](https://docs.guile.app/problems/paymentMethodNotSet) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '429': description: >- Too Many Requests. The client has sent too many requests in a given amount of time. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/tooManyRequests](https://docs.guile.app/problems/tooManyRequests) headers: Retry-After: required: true description: The number of seconds to wait before retrying the request. schema: type: integer format: uint32 content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '500': description: >- Internal Server Error. The server encountered an unexpected condition that prevented it from fulfilling the request. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/internalServerError](https://docs.guile.app/problems/internalServerError) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' security: - BearerAuth: [] components: parameters: idempotencyKeyRequest: name: Idempotency-Key in: header required: true description: >- A client-generated idempotency key to ensure operations are only processed once even if a client retries the operation. The V4 UUID format, as defined in [RFC 4122](https://tools.ietf.org/html/rfc4122), is recommended to avoid collisions but is not required. schema: type: string maxLength: 255 schemas: resourceId: type: string description: >- 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. barberAppointmentDetail: type: object required: - appointment properties: appointment: allOf: - $ref: '#/components/schemas/appointment' description: The appointment resource. client: allOf: - $ref: '#/components/schemas/clientReference' description: The barber's client record linked to the appointment customer. bookingMessage: type: string maxLength: 500 description: The customer message saved with the appointment at booking time. referencePhotos: type: array items: $ref: '#/components/schemas/Photos.PhotoReference' maxItems: 3 description: >- Approved appointment reference photos visible to the barber and customer. cancellation: allOf: - $ref: '#/components/schemas/appointmentCancellation' description: The cancellation decision recorded when the appointment is canceled. cancellationFeePreviews: allOf: - $ref: '#/components/schemas/appointmentCancellationFeePreviews' description: The fee amounts available before a cancellation decision. description: A barber-facing representation of an appointment. apiProblem: type: object required: - type - title - occurredAt - id - status properties: type: allOf: - $ref: '#/components/schemas/uri' description: A URI reference that identifies the problem type. title: type: string maxLength: 120 description: >- A short, human-readable summary of the problem type. The title is usually the same for all problems with the same `type`. occurredAt: type: string format: date-time description: >- The date-time when this problem occurred, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived and immutable. detail: type: string maxLength: 256 description: >- A human-readable explanation specific to this occurrence of the problem. id: allOf: - $ref: '#/components/schemas/resourceId' description: >- The unique identifier for this problem. This is an immutable opaque string. status: allOf: - $ref: '#/components/schemas/statusCode' description: >- The [HTTP status code](https://datatracker.ietf.org/doc/html/rfc7231#section-6)for this occurrence of the problem. instance: allOf: - $ref: '#/components/schemas/uri' maxLength: 2048 description: >- A URI reference that identifies the specific occurrence of the problem. This is the URI of an API resource that the problem is related to, with a unique error correlation ID URI fragment. attributes: type: object additionalProperties: {} description: >- Additional optional attributes related to the problem. This data conforms to the schema associated with the error type. recovery: allOf: - $ref: '#/components/schemas/clientFailureRecovery' description: The recovery contract for this problem occurrence. problems: type: array items: $ref: '#/components/schemas/problem' maxItems: 128 description: |- Optional root-causes if there are multiple problems in the request or API call processing. description: >- API problem or error response, as per [RFC 9457 application/problem+json](https://tools.ietf.org/html/rfc9457). appointment: type: object required: - givenName - services - occursOn - duration - cost - barber - location - id - createdAt - updatedAt - state - paymentState - totalAuthorized - totalCaptured - totalRefunded properties: givenName: type: string minLength: 1 maxLength: 55 format: text description: The given name of the customer. services: type: array items: $ref: '#/components/schemas/Common.ServiceReference' description: The services for this appointment. occursOn: type: string format: date-time description: |- The date and time the appointment occurs on. This is expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) `YYYY-MM-DDThh:mm:ss.sssZ` date-time format in UTC time zone. duration: type: string format: duration description: >- The duration of the appointment. The value is an [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) string. For example, an appointment lasting 30 minutes would be represented as `PT30M`. cost: allOf: - $ref: '#/components/schemas/money' description: The cost of the appointment, excluding any tips, fees or taxes. paymentMethodSource: allOf: - $ref: '#/components/schemas/appointmentPaymentMethod' description: >- 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. pendingType: allOf: - $ref: '#/components/schemas/appointmentPendingType' description: >- 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. bookingRequest: allOf: - $ref: '#/components/schemas/appointmentBookingRequest' description: >- 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. barber: allOf: - $ref: '#/components/schemas/appointmentBarberReference' description: The barber for this appointment. location: allOf: - $ref: '#/components/schemas/appointmentLocationReference' description: The location for this appointment. offHoursFee: allOf: - $ref: '#/components/schemas/money' description: |- 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. openingBand: allOf: - $ref: '#/components/schemas/appointmentOpeningBand' description: |- The opening band accepted when the appointment was created. This is derived and immutable. tipAmount: allOf: - $ref: '#/components/schemas/money' description: >- The tip the customer selected at booking time, when one was included. Not charged until capture. surname: type: string minLength: 1 maxLength: 55 format: text description: >- The customer's full surname when the authenticated barber may see it. displayName: type: string description: >- The customer name the authenticated barber may display under the customer's surname visibility preference. timeZone: type: string allOf: - $ref: '#/components/schemas/ianaTimeZone' nullable: true description: The IANA time zone for the appointment occurrence. id: $ref: '#/components/schemas/resourceId' recurringAppointmentId: allOf: - $ref: '#/components/schemas/resourceId' description: >- 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. createdAt: type: string format: date-time description: |- The date-time when this resource was created, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived and immutable. updatedAt: type: string format: date-time description: |- The date-time when this resource was updated, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived and immutable. state: allOf: - $ref: '#/components/schemas/appointmentState' description: The appointment state. This is derived and immutable. paymentState: allOf: - $ref: '#/components/schemas/appointmentPaymentState' description: The payment state of the appointment. This is derived and immutable. cancelationFeeType: allOf: - $ref: '#/components/schemas/appointmentCancelationFeeType' description: >- If included, the type of cancelation fee incurred. This is derived and immutable. paymentLinkSend: allOf: - $ref: '#/components/schemas/appointmentPaymentLinkSend' description: If included, the payment-link send state for this appointment. bookingMessage: type: string maxLength: 500 description: >- The customer message saved with the appointment. Visible only to the appointment's barber and customer. referencePhotos: type: array items: $ref: '#/components/schemas/Photos.PhotoReference' maxItems: 3 description: >- Immutable 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. cancellation: allOf: - $ref: '#/components/schemas/appointmentCancellation' description: The cancellation decision recorded when the appointment is canceled. cancellationFeePreviews: allOf: - $ref: '#/components/schemas/appointmentCancellationFeePreviews' description: The fee amounts available before a cancellation decision. deposit: allOf: - $ref: '#/components/schemas/appointmentDeposit' description: >- The required deposit for this appointment. Percentage deposits exclude tips, taxes, Guile fees, processing fees, and off-hours fees. totalAuthorized: allOf: - $ref: '#/components/schemas/money' description: The sum amount of authorized payments for this appointment. totalCaptured: allOf: - $ref: '#/components/schemas/money' description: The sum amount of captured payments for this appointment. totalRefunded: allOf: - $ref: '#/components/schemas/money' description: The sum amount of refunded payments for this appointment. calendarEventUrl: allOf: - $ref: '#/components/schemas/uri' description: >- 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. reviewed: type: boolean description: >- Whether the appointment's customer has already submitted a review for this visit. Present for the owning customer; omitted for other audiences. reviewPromptDismissed: type: boolean description: >- 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. description: A representation of an appointment. clientReference: type: object required: - id properties: id: allOf: - $ref: '#/components/schemas/resourceId' description: The unique identifier for the client record. description: A reference to a barber's client record. Photos.PhotoReference: type: object required: - id - url properties: id: allOf: - $ref: '#/components/schemas/resourceId' description: The unique identifier for the photo. url: allOf: - $ref: '#/components/schemas/uri' description: The URL to access the photo. thumbnailUrl: allOf: - $ref: '#/components/schemas/uri' description: The URL for the optimized photo preview. description: A reference to a photo. appointmentCancellation: type: object required: - actor - reason - canceledAt properties: actor: allOf: - $ref: '#/components/schemas/appointmentCancellationActor' description: The party responsible for the cancellation. reason: allOf: - $ref: '#/components/schemas/appointmentCancellationReason' description: The reason category selected for the cancellation. note: type: string maxLength: 500 description: The client-visible cancellation note. policySnapshot: allOf: - $ref: '#/components/schemas/appointmentCancellationPolicySnapshot' description: >- The cancellation policy preserved from when the appointment was booked. fee: allOf: - $ref: '#/components/schemas/appointmentCancellationFee' description: >- The fee derived from the preserved policy when this cancellation incurs one. canceledAt: type: string format: date-time description: |- The date-time when the appointment was canceled, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived and immutable. description: The cancellation decision recorded for a canceled appointment. appointmentCancellationFeePreviews: type: object required: - lateCancellation - noShow properties: lateCancellation: allOf: - $ref: '#/components/schemas/appointmentLateCancellationFeePreview' description: >- The fee amount and current customer-cancellation applicability for a late cancellation. noShow: allOf: - $ref: '#/components/schemas/appointmentCancellationFeePreview' description: The fee amount for a no-show. description: >- The separate late-cancellation and no-show fee amounts for an appointment. uri: type: string maxLength: 1024 format: uri description: A URI reference to an internal or external resource. statusCode: type: integer format: uint16 minimum: 100 maximum: 599 description: The HTTP status code for a response. clientFailureRecovery: type: object required: - outcome - retry properties: outcome: allOf: - $ref: '#/components/schemas/clientFailureOutcome' description: The known outcome of the request. retry: allOf: - $ref: '#/components/schemas/clientRetryDirective' description: The safe retry action for the request. sessionAction: allOf: - $ref: '#/components/schemas/clientSessionAction' description: The session action required before the request can continue. rateLimit: allOf: - $ref: '#/components/schemas/rateLimit' description: The rate limit state that prevented the request. description: The recovery contract for a failed client request. problem: type: object required: - type - title - occurredAt - id - status properties: type: allOf: - $ref: '#/components/schemas/uri' description: A URI reference that identifies the problem type. title: type: string maxLength: 120 description: >- A short, human-readable summary of the problem type. The title is usually the same for all problems with the same `type`. occurredAt: type: string format: date-time description: >- The date-time when this problem occurred, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived and immutable. detail: type: string maxLength: 256 description: >- A human-readable explanation specific to this occurrence of the problem. id: allOf: - $ref: '#/components/schemas/resourceId' description: >- The unique identifier for this problem. This is an immutable opaque string. status: allOf: - $ref: '#/components/schemas/statusCode' description: >- The [HTTP status code](https://datatracker.ietf.org/doc/html/rfc7231#section-6)for this occurrence of the problem. instance: allOf: - $ref: '#/components/schemas/uri' maxLength: 2048 description: >- A URI reference that identifies the specific occurrence of the problem. This is the URI of an API resource that the problem is related to, with a unique error correlation ID URI fragment. attributes: type: object additionalProperties: {} description: >- Additional optional attributes related to the problem. This data conforms to the schema associated with the error type. description: >- Standard problem or error response, as per [RFC 9457 application/problem+json](https://tools.ietf.org/html/rfc9457). Common.ServiceReference: type: object required: - id properties: id: allOf: - $ref: '#/components/schemas/resourceId' description: The unique identifier for the service. name: type: string description: The display name for this service. cost: allOf: - $ref: '#/components/schemas/money' description: The cost of the service, excluding any fees or taxes. duration: type: string format: duration description: The duration of the service. description: |- A reference to a service resource. This contains a subset of properties for the service. Use Service for the full resource entity. money: type: string pattern: ^-?(0|[1-9][0-9]*)\.[0-9][0-9]$ format: decimal description: >- A monetary amount in the lowest denomination for the given currency. The numeric value is represented as a string so that it can be exact with no loss of precision. Values may be positive or negative. example: '456.78' appointmentPaymentMethod: type: string enum: - platform - external description: |- The method used to process the payment. `platform` means Guile manages the payment through our payment provider. `external` means the payment is managed externally. This is either cash or a peer-to-peer payment system, such as Venmo. appointmentPendingType: type: string enum: - bookingApproval - cardConfirmation description: Why an appointment is pending. appointmentBookingRequest: type: object required: - state - value - expiresAt properties: state: allOf: - $ref: '#/components/schemas/appointmentBookingRequestState' description: The current booking-request decision state. value: allOf: - $ref: '#/components/schemas/appointmentBookingRequestValue' description: The immutable value of the request as shown to the barber. expiresAt: type: string format: date-time description: >- The server-owned UTC deadline for a barber decision. It is never later than the appointment occurrence. resolvedAt: type: string format: date-time description: When a terminal request decision was committed. declineReason: type: string maxLength: 500 description: >- The client-visible reason supplied by the barber for a rejected request. expirationReason: allOf: - $ref: '#/components/schemas/appointmentBookingRequestExpirationReason' description: Why the request expired. description: >- The immutable value, deadline, and resolution of a booking request embedded in its appointment. This is not a separate top-level resource. appointmentBarberReference: type: object required: - id - givenName - surname properties: id: allOf: - $ref: '#/components/schemas/resourceId' description: The unique identifier of the barber profile. givenName: type: string minLength: 1 maxLength: 55 format: text description: The given name of the barber. surname: type: string minLength: 1 maxLength: 55 format: text description: The surname of the barber. preferredName: type: string maxLength: 55 format: text description: The preferred name of the barber. biography: type: string maxLength: 2000 format: text description: A short biography of the barber. spokenLanguages: type: array items: $ref: '#/components/schemas/spokenLanguageTag' minItems: 1 description: Languages the barber speaks, as IETF BCP 47 language tags. experience: type: integer format: int32 minimum: 0 maximum: 100 description: |- Years of professional barbering experience. Omitted when the barber has not set a value. instagram: type: string minLength: 1 maxLength: 30 pattern: ^[A-Za-z0-9](?:[A-Za-z0-9._]{0,28}[A-Za-z0-9])?$ description: |- Public Instagram username for the booking page, without a leading @. Absent when unset. Not a private messaging channel. urlSlug: allOf: - $ref: '#/components/schemas/bookingSlug' description: The barber's public booking slug, used in profile links. profileImage_URL: type: string maxLength: 255 format: uri description: A URL to the barber's profile image. phoneNumber: allOf: - $ref: '#/components/schemas/formattedPhoneNumber' description: >- The barber's phone number, visible only to the customer who owns the appointment. description: A barber reference on an appointment response. appointmentLocationReference: type: object required: - id - name - shopName properties: id: allOf: - $ref: '#/components/schemas/resourceId' description: |- The unique identifier for this shop location reference. This is an immutable opaque string. name: type: string description: The name of this location for a shop. shopName: type: string description: The name of the shop business entity. address: allOf: - $ref: '#/components/schemas/usAddress' description: The street address of the appointment location. description: A shop location reference on an appointment response. appointmentOpeningBand: type: string enum: - regular - beforeHours - afterHours description: Which part of the barber's day an opening belongs to. ianaTimeZone: type: string description: An IANA time-zone identifier. appointmentState: type: string enum: - pending - scheduled - canceled - completed - rejected - expired description: Valid states of the appointment. appointmentPaymentState: type: string enum: - pending - processing - authorized - paid - failed description: |- The money position of an appointment's payment. `pending` means no funds have moved. `processing` means an authorization or capture attempt is in flight. `authorized` means funds are held but not captured, `paid` means captured and settled, and `failed` means the last authorization attempt failed. appointmentCancelationFeeType: type: string enum: - lateCancelation - noShow description: Indicates the fee type for cancelations. appointmentPaymentLinkSend: type: object required: - state - reason - attemptsUsed - attemptsRemaining - maxAttempts properties: state: allOf: - $ref: '#/components/schemas/appointmentPaymentLinkSendState' description: The send state. reason: allOf: - $ref: '#/components/schemas/appointmentPaymentLinkSendReason' description: Why this appointment can receive a payment link send. attemptsUsed: type: integer format: int32 minimum: 0 description: The number of sends used in this cycle. attemptsRemaining: type: integer format: int32 minimum: 0 description: The number of sends left in this cycle. maxAttempts: type: integer format: int32 minimum: 0 description: The number of sends allowed in this cycle. nextAvailableAt: type: string format: date-time description: |- The next RFC 3339 UTC date-time when another payment link can be scheduled for this appointment, if any. lastSentAt: type: string format: date-time description: >- The most recent RFC 3339 UTC date-time a payment link was sent for this appointment, if any. description: >- The payment-link send state for an appointment. Backoff may apply after a successful send; use `state` and `nextAvailableAt` to decide when another send can be scheduled. appointmentDeposit: type: object required: - amount - paymentState - refundedAmount properties: amount: allOf: - $ref: '#/components/schemas/money' description: The server-calculated deposit amount. paymentState: allOf: - $ref: '#/components/schemas/appointmentPaymentState' description: The current payment state of the deposit. refundedAmount: allOf: - $ref: '#/components/schemas/money' description: The amount of the captured deposit that has been refunded. description: The required deposit and its current payment state. appointmentCancellationActor: type: string enum: - barber - client description: The party responsible for an appointment cancellation. appointmentCancellationReason: type: string enum: - clientCanceled - noShow - barberCanceled - other description: The reason category selected for an appointment cancellation. appointmentCancellationPolicySnapshot: type: object required: - lateCancellationWindow - lateCancellationFee - noShowFee properties: lateCancellationWindow: type: string format: duration description: >- The window before the appointment start when a cancellation becomes late. lateCancellationFee: allOf: - $ref: '#/components/schemas/appointmentCancellationFeePolicySnapshot' description: >- The late-cancellation fee policy in force when the appointment was booked. noShowFee: allOf: - $ref: '#/components/schemas/appointmentCancellationFeePolicySnapshot' description: The no-show fee policy in force when the appointment was booked. description: The cancellation policy preserved from when the appointment was booked. appointmentCancellationFee: type: object required: - type - amount - currencyCode - applied properties: type: allOf: - $ref: '#/components/schemas/appointmentCancelationFeeType' description: The fee category derived from the cancellation reason. amount: allOf: - $ref: '#/components/schemas/money' description: The fee amount derived from the preserved policy. currencyCode: type: string minLength: 3 maxLength: 3 description: >- The [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) for `amount`. example: USD applied: type: boolean description: Whether the derived fee amount was applied to the appointment. description: The cancellation fee recorded for a canceled appointment. appointmentLateCancellationFeePreview: type: object required: - appliesNow properties: appliesNow: type: boolean description: >- Whether a customer cancellation at read time would apply the late-cancellation fee. freeUntil: type: string format: date-time description: >- The date-time until which customer cancellation remains free, when known. freeReason: allOf: - $ref: '#/components/schemas/appointmentLateCancellationFreeReason' description: Why customer cancellation is currently free. allOf: - $ref: '#/components/schemas/appointmentCancellationFeePreview' description: >- The late-cancellation fee amount and whether a customer cancellation would apply it now. appointmentCancellationFeePreview: type: object required: - amount - currencyCode properties: amount: allOf: - $ref: '#/components/schemas/money' description: The cancellation fee amount. currencyCode: type: string minLength: 3 maxLength: 3 description: >- The [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) for `amount`. example: USD description: >- A cancellation fee amount calculated from the appointment policy snapshot. clientFailureOutcome: type: string enum: - notApplied - unknown description: The known outcome of a failed client request. clientRetryDirective: type: string enum: - doNotRetry - retrySameRequest - retrySameRequestAfterDelay description: The safe retry action for a failed client request. clientSessionAction: type: string enum: - refresh - signIn description: The session action required before a failed request can continue. rateLimit: type: object required: - limit - remaining - resetsAt properties: limit: type: integer format: uint64 description: The maximum number of requests allowed in the active window. remaining: type: integer format: uint64 description: The number of requests remaining in the active window. resetsAt: type: string format: date-time description: >- The date-time when the active window resets, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. description: The rate limit state for the request. appointmentBookingRequestState: type: string enum: - pending - confirming - confirmed - rejected - expired - canceled description: The decision lifecycle of an embedded booking request. appointmentBookingRequestValue: type: object required: - serviceSubtotal - total properties: serviceSubtotal: allOf: - $ref: '#/components/schemas/money' description: >- The preserved service and add-on subtotal, excluding tips, fees, and taxes. offHoursFee: allOf: - $ref: '#/components/schemas/money' description: The preserved off-hours fee, when one applies. tipAmount: allOf: - $ref: '#/components/schemas/money' description: The customer's selected tip intent, when one was included. total: allOf: - $ref: '#/components/schemas/money' description: |- The sum of `serviceSubtotal`, `offHoursFee`, and `tipAmount`. This excludes taxes, platform fees, and other payment-processing amounts. description: Immutable monetary value captured when a booking request is created. appointmentBookingRequestExpirationReason: type: string enum: - approvalTimedOut description: Why an approval-pending booking request expired. spokenLanguageTag: type: string enum: - ar - de - en - es - fr - ko - ru - tl - vi - zh description: An IETF BCP 47 language tag supported on barber profiles. bookingSlug: type: string minLength: 3 maxLength: 40 pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ description: A barber's public booking slug, used in profile links. formattedPhoneNumber: type: string minLength: 6 maxLength: 32 format: phoneNumber description: A formatted phone number. usAddress: type: object required: - address1 - locality - regionCode - postalCode - countryCode properties: address1: type: string maxLength: 35 description: >- The first line of the postal address. In the US, this typically includes the building number and street name. address2: type: string maxLength: 35 description: |- The second line of the street address. This should only be used if it has a value. Typical values include building numbers, suite numbers, and other identifying information beyond the first line of the postal address. locality: type: string maxLength: 30 description: The city/town/municipality of the address. example: Atlanta regionCode: type: string minLength: 2 maxLength: 2 pattern: ^[A-Za-z]{2}$ description: The state, district, or outlying area of the postal address. example: VT postalCode: type: string minLength: 5 maxLength: 10 pattern: ^\d{5}(?:[- ]?\d{4})?$ description: >- A group of five or nine numbers that are added to a postal address to assist the sorting of mail. example: 20521-9000 countryCode: type: string minLength: 2 maxLength: 2 pattern: ^[A-Za-z]{2}$ description: The ISO-3611 alpha-2 value for a country. example: CA description: A postal address within the United States or US territories. appointmentPaymentLinkSendState: type: string enum: - available - sending - cooldown - exhausted description: The current state of appointment payment-link sending. appointmentPaymentLinkSendReason: type: string enum: - manualNoCard - savedCardAuthorizationFailed - savedCardCaptureFailed description: The appointment condition that makes payment-link sending available. appointmentCancellationFeePolicySnapshot: type: object required: - type properties: type: allOf: - $ref: '#/components/schemas/appointmentCancellationFeePolicyType' description: The fee calculation method in force when the appointment was booked. fixed: allOf: - $ref: '#/components/schemas/money' description: The fixed fee, present when `type` is `fixed`. currencyCode: type: string minLength: 3 maxLength: 3 description: >- The [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) for `fixed`, present when `type` is `fixed`. example: USD percentage: type: integer format: int8 minimum: 0 maximum: 100 description: >- The percentage of the appointment cost, present when `type` is `percentage`. description: A fee policy preserved from the appointment when it was booked. appointmentLateCancellationFreeReason: type: string enum: - noFeeConfigured - outsideLateWindow - pendingRequest - bookingGrace - confirmationGrace - rescheduleGrace description: Why a customer cancellation is currently free. appointmentCancellationFeePolicyType: type: string enum: - none - fixed - percentage description: The fee calculation method preserved with an appointment. securitySchemes: BearerAuth: type: http scheme: Bearer ````