> ## 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.

# Refund an appointment payment

> Refund a captured appointment payment in whole or in part.



## OpenAPI

````yaml /api-reference/Appointments/openapi.yaml post /appointments/{appointmentId}/payments/{paymentId}/refunds
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:
  /appointments/{appointmentId}/payments/{paymentId}/refunds:
    post:
      tags:
        - Appointments
      summary: Refund an appointment payment
      description: Refund a captured appointment payment in whole or in part.
      operationId: refundAppointmentPayment
      parameters:
        - $ref: '#/components/parameters/idempotencyKeyRequest'
        - name: appointmentId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/resourceId'
        - name: paymentId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/resourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/refundPaymentRequest'
            examples:
              example0:
                value:
                  amount: '500.00'
              example1:
                value:
                  amount: '15.00'
                  reason: Customer left early
      responses:
        '200':
          description: |-
            Ok.
            The operation succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/appointmentPayment'
              example:
                id: 0190f0c0-5555-7555-8555-555555555555
                paymentMethod: platform
                paymentDirection: refund
                paymentState: paid
                amount: '45.00'
                guileFeeAmount: '0.00'
                createdAt: '2026-08-01T16:00:00.000Z'
                updatedAt: '2026-08-01T16:00:00.000Z'
        '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/paymentNotCaptured](https://docs.guile.app/problems/paymentNotCaptured)

            *
            [https://docs.guile.app/problems/refundAmountExceedsAvailable](https://docs.guile.app/problems/refundAmountExceedsAvailable)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '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/refundWindowExpired](https://docs.guile.app/problems/refundWindowExpired)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
              example:
                id: 0190f0c0-cccc-7ccc-8ccc-cccccccccccc
                type: https://docs.guile.app/problems/refundAmountExceedsAvailable
                title: Refund Amount Exceeds Available
                status: 422
                detail: The refund exceeds the captured balance.
                occurredAt: '2026-08-01T16:00:00.000Z'
        '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'
      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.
    refundPaymentRequest:
      type: object
      required:
        - amount
      properties:
        amount:
          allOf:
            - $ref: '#/components/schemas/money'
          description: >-
            The amount to refund. Refunds cannot be issued for an amount greater
            than the captured amount minus previous refunds.
        reason:
          type: string
          maxLength: 500
          description: Optional reason for the refund.
      description: Request body for refunding a payment.
    appointmentPayment:
      type: object
      required:
        - id
        - paymentMethod
        - paymentDirection
        - paymentState
        - amount
        - guileFeeAmount
        - createdAt
        - updatedAt
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: Unique identifier for the payment.
        paymentMethod:
          allOf:
            - $ref: '#/components/schemas/appointmentPaymentMethod'
          description: The method used to process this payment.
        paymentDirection:
          allOf:
            - $ref: '#/components/schemas/appointmentPaymentDirection'
          description: The direction of the payment flow.
        paymentType:
          allOf:
            - $ref: '#/components/schemas/appointmentPaymentType'
          description: The appointment obligation this payment addresses, when known.
        paymentState:
          allOf:
            - $ref: '#/components/schemas/appointmentPaymentState'
          description: The payment state.
        authorizationScheduledAt:
          type: string
          format: date-time
          description: >-
            When a saved-card authorization hold is scheduled to be placed for
            this payment.
        failureReason:
          allOf:
            - $ref: '#/components/schemas/paymentAuthorizationFailureReason'
          description: The authorization failure reason when a hold attempt fails.
        providerDeclineCode:
          type: string
          description: >-
            The provider decline code returned by the payment processor, when
            one is available.
        networkAdviceCode:
          type: string
          description: >-
            The card network advice code returned by the payment processor, when
            one is available.
        amount:
          allOf:
            - $ref: '#/components/schemas/money'
          description: The amount of this payment.
        currencyCode:
          type: string
          minLength: 3
          maxLength: 3
          description: >-
            The [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217)
            for this payment's monetary values.
          example: USD
        tipAmount:
          allOf:
            - $ref: '#/components/schemas/money'
          description: The tip included in the payable total, when one has been selected.
        offHoursFeeAmount:
          allOf:
            - $ref: '#/components/schemas/money'
          description: |-
            The off-hours fee included in this payment, when the payment settles
            that preserved booking component.
        guileFeeAmount:
          allOf:
            - $ref: '#/components/schemas/money'
          description: The Guile fee charged with this payment.
        payableTotal:
          allOf:
            - $ref: '#/components/schemas/money'
          description: The full amount due for the appointment, including the selected tip.
        paymentProblem:
          allOf:
            - $ref: '#/components/schemas/appointmentPaymentProblem'
          description: A payment issue requiring follow-up.
        paymentToken:
          type: string
          description: For external payments, the token representing the payment.
        externalId:
          type: string
          description: >-
            External identifier for the payment from the payment processor or
            external system.
        card:
          allOf:
            - $ref: '#/components/schemas/appointmentPaymentCard'
          description: >-
            The card charged for this payment, when Guile recorded the network
            and

            last four digits from the payment processor. Omitted for cash or

            external payments, and when Guile never recorded a card for the
            charge.
        originalPaymentId:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: For refund payments, the original payment being refunded.
        refundReason:
          type: string
          maxLength: 500
          description: For refund payments, the reason for the refund.
        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.
      description: Represents a payment associated with 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).
    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.
    appointmentPaymentDirection:
      type: string
      enum:
        - payment
        - refund
      description: |-
        The direction of the payment flow.

        `payment` means money flows from customer to business.
        `refund` means money flows from business to customer.
    appointmentPaymentType:
      type: string
      enum:
        - authorization
        - deposit
        - balance
      description: The appointment obligation addressed by a payment.
    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.
    paymentAuthorizationFailureReason:
      type: string
      enum:
        - declined
        - cardUnusable
        - processingError
        - other
      description: Reasons a saved-card authorization can fail.
    appointmentPaymentProblem:
      type: string
      enum:
        - authorizationRepairFailed
      description: Payment issues requiring follow-up.
    appointmentPaymentCard:
      type: object
      required:
        - network
        - last4
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: >-
            The payment processor identifier for the card, when Guile recorded
            it.
        network:
          allOf:
            - $ref: '#/components/schemas/cardNetwork'
          description: The card network facilitating the money movement.
        last4:
          type: string
          description: The last 4 digits of the card number.
      description: The card display facts Guile recorded for an appointment payment.
    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).
    cardNetwork:
      type: string
      enum:
        - visa
        - discover
        - mastercard
        - amex
        - other
      description: The card payment processing network.
    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.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: Bearer

````