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

# List my payments

> List the current customer's appointment payments across barbers.

Each row is one payment plus the appointment facts needed to render a
receipt history entry without further appointment or payment reads.



## OpenAPI

````yaml /api-reference/Customers/openapi.yaml get /me/payments
openapi: 3.0.0
info:
  title: Customers
  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: The Customer API provides operations for customers on the Guile platform.
servers:
  - url: https://api.guile.app
    variables: {}
  - url: https://guile.fly.dev
    variables: {}
security: []
tags:
  - name: Customers
    description: Customer profile, cards on file, and bookings
paths:
  /me/payments:
    get:
      tags:
        - Customers
      summary: List my payments
      description: |-
        List the current customer's appointment payments across barbers.

        Each row is one payment plus the appointment facts needed to render a
        receipt history entry without further appointment or payment reads.
      operationId: listMyPayments
      parameters:
        - name: paymentMethod
          in: query
          required: false
          description: |-
            When included, filter to payments with any of these payment methods.
            When excluded, payments are not filtered by payment method.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/appointmentPaymentMethod'
          explode: false
          style: pipeDelimited
        - name: paymentDirection
          in: query
          required: false
          description: >-
            When included, filter to payments with any of these payment
            directions.

            When excluded, defaults to payment (charges), not refunds.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/appointmentPaymentDirection'
            default:
              - payment
          explode: false
          style: pipeDelimited
        - name: paymentState
          in: query
          required: false
          description: |-
            When included, filter to payments with any of these payment states.
            When excluded, defaults to paid payments.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/appointmentPaymentState'
            default:
              - paid
          explode: false
          style: pipeDelimited
        - name: date
          in: query
          required: false
          description: >-
            When included, filter to payments whose appointment occurs within
            this

            date range. When excluded, payments are not filtered by appointment
            date.
          schema:
            $ref: '#/components/schemas/dateRange'
          explode: false
        - name: limit
          in: query
          required: true
          schema:
            type: integer
            format: int16
            default: 10
          explode: false
        - name: offset
          in: query
          required: true
          schema:
            type: integer
            format: int16
            default: 0
          explode: false
      responses:
        '200':
          description: |-
            Ok.
            The operation succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerPayments'
        '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'
        '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:
  schemas:
    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.
    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.
    dateRange:
      type: string
      maxLength: 24
      pattern: >-
        ^(\d{4}-\d{2}-\d{2}|[\[(](\d{4}-\d{2}-\d{2},(\d{4}-\d{2}-\d{2})?|,\d{4}-\d{2}-\d{2})[)\]])$
      description: >-
        A date range, supporting inclusive or exclusive endpoints.

        Dates ranges use dates expressed in `YYYY-MM-DD` [RFC
        3339](https://tools.ietf.org/html/rfc3339)

        `date` format.

        The value may have the following forms:

        - `YYYY-MM-DD` match the date exactly; equivalent to matching dates in
        the range `[YYYY-MM-DD,YYYY-MM-DD]`

        - `[YYYY-MM-DD,YYYY-MM-DD]` between two dates, inclusive of the
        endpoints

        - `(YYYY-MM-DD,YYYY-MM-DD)` between two dates, exclusive of the
        endpoints

        - `[YYYY-MM-DD,]` on or after the date

        - `(YYYY-MM-DD,)` after the date

        - `[,YYYY-MM-DD]` before or on the date

        - `(,YYYY-MM-DD)` before the date


        Examples:

        - '2022-05-19'

        - '[2022-05-01,2022-05-31]'

        - '[2022-05-01,2022-06-01)'

        - '[2022-05-19,]'

        - '(2022-05-19,)'

        - '[,2022-05-19]'

        - '(,2022-05-19)'.
    customerPayments:
      type: object
      required:
        - items
        - count
        - offset
        - limit
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/customerPayment'
          minItems: 0
        count:
          type: integer
          format: int16
          minimum: 0
        offset:
          type: integer
          format: int16
          minimum: 0
          description: The offset of list results for the current page.
        limit:
          type: integer
          format: int16
          minimum: 0
          description: The maximum number of results included in `items`.
      description: A paginated list of the current customer's appointment payments.
    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).
    customerPayment:
      type: object
      required:
        - id
        - paymentMethod
        - paymentDirection
        - paymentState
        - amount
        - guileFeeAmount
        - createdAt
        - updatedAt
        - appointmentId
        - occursOn
        - barber
        - location
        - services
        - totalCaptured
        - totalRefunded
      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.
        appointmentId:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: The appointment this payment belongs to.
        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.
        timeZone:
          type: string
          allOf:
            - $ref: '#/components/schemas/ianaTimeZone'
          nullable: true
          description: The IANA time zone for the appointment occurrence.
        barber:
          allOf:
            - $ref: '#/components/schemas/Common.BarberReference'
          description: The barber for the appointment.
        location:
          allOf:
            - $ref: '#/components/schemas/Common.ShopLocationReference'
          description: The location for the appointment.
        services:
          type: array
          items:
            $ref: '#/components/schemas/Common.ServiceReference'
          description: The services captured on the appointment.
        appointmentState:
          allOf:
            - $ref: '#/components/schemas/appointmentState'
          description: The appointment state when available.
        totalCaptured:
          allOf:
            - $ref: '#/components/schemas/money'
          description: The sum amount of captured payments for the appointment.
        totalRefunded:
          allOf:
            - $ref: '#/components/schemas/money'
          description: The sum amount of refunded payments for the appointment.
      description: >-
        A customer-visible appointment payment with the appointment context
        needed

        for receipt history.
    uri:
      type: string
      maxLength: 1024
      format: uri
      description: A URI reference to an internal or external resource.
    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.
    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).
    appointmentPaymentType:
      type: string
      enum:
        - authorization
        - deposit
        - balance
      description: The appointment obligation addressed by a payment.
    paymentAuthorizationFailureReason:
      type: string
      enum:
        - declined
        - cardUnusable
        - processingError
        - other
      description: Reasons a saved-card authorization can fail.
    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'
    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.
    ianaTimeZone:
      type: string
      description: An IANA time-zone identifier.
    Common.BarberReference:
      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.
      description: |-
        A reference to a barber resource. This contains a subset of properties
        for the barber. Use Barber for the full resource entity.
    Common.ShopLocationReference:
      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.
      description: |-
        A reference to a shop location. This contains a subset of properties
        for the location. Use ShopLocation for the full resource entity.
    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.
    appointmentState:
      type: string
      enum:
        - pending
        - scheduled
        - canceled
        - completed
        - rejected
        - expired
      description: Valid states of the appointment.
    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.
    cardNetwork:
      type: string
      enum:
        - visa
        - discover
        - mastercard
        - amex
        - other
      description: The card payment processing network.
    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.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: Bearer

````