> ## 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 a client's appointment history

> List past appointments for one of the authenticated barber's clients.
Results are ordered newest first and use offset pagination.
Each item summarizes one past appointment with its occurrence time,
services, cost, payment state, and history outcome (`completed`,
`canceled`, or `noShow`).



## OpenAPI

````yaml /api-reference/Clients/openapi.yaml get /clients/{clientId}/appointments
openapi: 3.0.0
info:
  title: Clients
  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 Clients API provides operations for managing a barber's clients
    within the Guile platform.
servers:
  - url: https://api.guile.app
    variables: {}
  - url: https://guile.fly.dev
    variables: {}
security: []
tags:
  - name: Groups
    description: Smart groups and booking rules for clients
  - name: Notes
    description: Private notes a barber keeps on a client
  - name: Clients
    description: A barber client roster
paths:
  /clients/{clientId}/appointments:
    get:
      tags:
        - Clients
      summary: List a client's appointment history
      description: |-
        List past appointments for one of the authenticated barber's clients.
        Results are ordered newest first and use offset pagination.
        Each item summarizes one past appointment with its occurrence time,
        services, cost, payment state, and history outcome (`completed`,
        `canceled`, or `noShow`).
      operationId: listClientAppointments
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/resourceId'
        - name: type
          in: query
          required: false
          description: |-
            History view filter. When `visits`, return the full past history
            (completed visits, cancellations, and no-shows). When `noShows`,
            return only no-show appointments. When omitted, return the full
            past history.
          schema:
            $ref: '#/components/schemas/clientAppointmentHistoryType'
          explode: false
        - name: offset
          in: query
          required: false
          description: The offset for pagination. Defaults to 0.
          schema:
            type: integer
            format: int16
            minimum: 0
            maximum: 32767
            default: 0
          explode: false
        - name: limit
          in: query
          required: false
          description: The maximum number of results to return. Defaults to 20.
          schema:
            type: integer
            format: int16
            minimum: 1
            maximum: 100
            default: 20
          explode: false
      responses:
        '200':
          description: |-
            Ok.
            The operation succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clientAppointmentHistoryList'
        '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'
        '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)
          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:
    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.
    clientAppointmentHistoryType:
      type: string
      enum:
        - visits
        - noShows
      description: |-
        History view filter for a client's past appointments.
        `visits` is the full past history. `noShows` returns only no-shows.
    clientAppointmentHistoryList:
      type: object
      required:
        - items
        - count
        - offset
        - limit
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/clientAppointmentHistoryItem'
          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 a client's past appointments, newest first.
    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).
    clientAppointmentHistoryItem:
      type: object
      required:
        - id
        - occursOn
        - services
        - cost
        - outcome
        - paymentState
      properties:
        id:
          $ref: '#/components/schemas/resourceId'
        occursOn:
          type: string
          format: date-time
          description: |-
            The date and time the appointment occurred, in
            [RFC 3339](https://tools.ietf.org/html/rfc3339)
            `YYYY-MM-DDThh:mm:ss.sssZ` date-time format in UTC.
        timeZone:
          type: string
          allOf:
            - $ref: '#/components/schemas/ianaTimeZone'
          nullable: true
          description: The IANA time zone for the appointment occurrence.
        services:
          type: array
          items:
            $ref: '#/components/schemas/Common.ServiceReference'
          description: The services for this appointment.
        cost:
          allOf:
            - $ref: '#/components/schemas/money'
          description: The cost of the appointment, excluding tips, fees, or taxes.
        outcome:
          allOf:
            - $ref: '#/components/schemas/clientAppointmentHistoryOutcome'
          description: The outcome of this past appointment in the client's history.
        paymentState:
          allOf:
            - $ref: '#/components/schemas/appointmentPaymentState'
          description: The payment state of the appointment.
      description: A past appointment summary for one of a barber's clients.
    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).
    ianaTimeZone:
      type: string
      description: An IANA time-zone identifier.
    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'
    clientAppointmentHistoryOutcome:
      type: string
      enum:
        - completed
        - canceled
        - noShow
      description: |-
        The history-row outcome for a past appointment. Distinguishes completed
        visits, cancellations, and no-shows.
    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.
    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

````