> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.golance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List scheduled payments

> Returns scheduled payments on fixed-price contracts for the authenticated company over a UTC date range. Each item includes the payment amount, paid amount, status, scheduled date, and parent contract. Filter by team, contractor, or payment status, and sort or paginate the results. The response also includes summary statistics for the same period.



## OpenAPI

````yaml /openapi.json get /scheduled-payments
openapi: 3.0.0
info:
  title: goLance External API
  version: 1.0.0
servers:
  - url: https://external-api.golance.com
security: []
paths:
  /scheduled-payments:
    get:
      tags:
        - Scheduled Payments
      summary: List scheduled payments
      description: >-
        Returns scheduled payments on fixed-price contracts for the
        authenticated company over a UTC date range. Each item includes the
        payment amount, paid amount, status, scheduled date, and parent
        contract. Filter by team, contractor, or payment status, and sort or
        paginate the results. The response also includes summary statistics for
        the same period.
      parameters:
        - schema:
            type: array
            items:
              type: string
            example:
              - 6137109712adad9757ab0e35
          required: false
          name: teamIds
          in: query
        - schema:
            type: string
            description: Start date in YYYY-MM-DD format
            example: '2026-08-01'
          required: true
          name: fromDate
          in: query
        - schema:
            type: string
            description: End date in YYYY-MM-DD format
            example: '2026-08-31'
          required: true
          name: toDate
          in: query
        - schema:
            type: array
            items:
              type: string
            example:
              - 6137109712adad9757ab0e35
          required: false
          name: contractorIds
          in: query
        - schema:
            type: array
            items:
              type: string
              enum:
                - upcoming
                - processing
                - failed
                - paid
                - deleted
            example:
              - upcoming
              - paid
          required: false
          name: scheduledPaymentStatuses
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          required: false
          name: sortOrder
          in: query
        - schema:
            type: string
            enum:
              - scheduledPaymentOn
              - date
              - budget
              - paidAmount
              - scheduledPaymentStatus
              - contract
              - contractor
            default: scheduledPaymentOn
          required: false
          name: sortField
          in: query
        - schema:
            type: integer
            minimum: 1
            default: 1
          required: false
          name: page
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          required: false
          name: itemsPerPage
          in: query
      responses:
        '200':
          description: >-
            A paginated list of scheduled payments plus period-level
            `statistics`. If the caller has no accessible company, `results` is
            empty.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        amount:
                          type: number
                        paidAmount:
                          type: number
                        status:
                          type: string
                          enum:
                            - upcoming
                            - processing
                            - failed
                            - paid
                            - deleted
                        scheduledPaymentOn:
                          type: string
                          nullable: true
                          description: Scheduled payment date (ISO 8601)
                        contract:
                          type: object
                          properties:
                            id:
                              type: string
                            title:
                              type: string
                            contractor:
                              type: object
                              properties:
                                id:
                                  type: string
                                firstName:
                                  type: string
                                lastName:
                                  type: string
                              required:
                                - id
                            employer:
                              type: object
                              properties:
                                id:
                                  type: string
                                firstName:
                                  type: string
                                lastName:
                                  type: string
                              required:
                                - id
                            team:
                              type: object
                              nullable: true
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                              required:
                                - id
                          required:
                            - id
                            - team
                      required:
                        - id
                        - amount
                        - paidAmount
                        - status
                        - scheduledPaymentOn
                        - contract
                  pagination:
                    type: object
                    properties:
                      currentPage:
                        type: number
                      itemsPerPage:
                        type: number
                      pagesCount:
                        type: number
                      totalCount:
                        type: number
                    required:
                      - currentPage
                      - itemsPerPage
                      - pagesCount
                      - totalCount
                  statistics:
                    type: object
                    properties:
                      contractsCount:
                        type: number
                      scheduledPaymentsCount:
                        type: number
                      paidScheduledPaymentsCount:
                        type: number
                      totalScheduledPaymentsPaidAmount:
                        type: number
                    required:
                      - contractsCount
                      - scheduledPaymentsCount
                      - paidScheduledPaymentsCount
                      - totalScheduledPaymentsPaidAmount
                required:
                  - results
                  - pagination
                  - statistics
        '400':
          description: >-
            The request body or query parameters failed validation. Returns
            `validation_error` and field-level `details`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code
                  message:
                    type: string
                    description: Human-readable error message
                  details:
                    type: object
                    additionalProperties:
                      nullable: true
                    description: Field-level validation errors
                required:
                  - error
                  - message
        '401':
          description: >-
            Authentication failed. The Bearer token is missing, invalid,
            expired, or not associated with a user. Common codes:
            `missing_token`, `invalid_token`, `unauthorized`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code
                  message:
                    type: string
                    description: Human-readable error message
                  details:
                    type: object
                    additionalProperties:
                      nullable: true
                    description: Field-level validation errors
                required:
                  - error
                  - message
        '403':
          description: >-
            The token was accepted, but the caller is not allowed to access this
            resource. Common codes: `forbidden`, `inactive_user`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code
                  message:
                    type: string
                    description: Human-readable error message
                  details:
                    type: object
                    additionalProperties:
                      nullable: true
                    description: Field-level validation errors
                required:
                  - error
                  - message
        '429':
          description: >-
            The client exceeded the rate limit of 200 requests per minute per IP
            address. Returns `rate_limited`. Wait for the `Retry-After` header
            before retrying.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code
                  message:
                    type: string
                    description: Human-readable error message
                  details:
                    type: object
                    additionalProperties:
                      nullable: true
                    description: Field-level validation errors
                required:
                  - error
                  - message
        '500':
          description: >-
            An unexpected error occurred while processing the request. Returns
            `internal_error`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code
                  message:
                    type: string
                    description: Human-readable error message
                  details:
                    type: object
                    additionalProperties:
                      nullable: true
                    description: Field-level validation errors
                required:
                  - error
                  - message
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````