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

# List bill payments

> Returns a list of bill payments for the specified business. Payments can be filtered by method and date range.



## OpenAPI

````yaml get /v1/businesses/{businessId}/bills/bill-payments
openapi: 3.0.1
info:
  title: API
  version: latest
servers: []
security:
  - BearerAuth: []
tags: []
externalDocs:
  url: /
paths:
  /v1/businesses/{businessId}/bills/bill-payments:
    get:
      tags: []
      summary: List bill payments
      description: >-
        Returns a list of bill payments for the specified business. Payments can
        be filtered by method and date range.
      operationId: business.bills.payments.get
      parameters:
        - name: businessId
          in: path
          description: The UUID of the business to fetch bill payments for.
          required: true
          schema:
            type: string
            format: uuid
        - name: reference_number
          in: query
          description: >-
            Filter by exact reference number match. Returns only records with
            this exact reference number.
          required: false
          schema:
            type: string
        - name: reference_numbers
          in: query
          description: >-
            Comma-separated list of reference numbers to filter bill payments
            by. Only bill payments with reference numbers matching any value in
            this list will be returned.
          required: false
          schema:
            type: string
        - name: method
          in: query
          description: Filter payments by method.
          schema:
            $ref: '#/components/schemas/PaymentMethod'
        - name: paid_at_start
          in: query
          description: >-
            Filter payments by payment date. Payments made on or after this date
            will be included.
          schema:
            type: string
            format: date-time
        - name: paid_at_end
          in: query
          description: >-
            Filter payments by payment date. Payments made on or before this
            date will be included.
          schema:
            type: string
            format: date-time
        - name: external_id
          in: query
          description: >-
            Filter payments by external ID (unique idempotency key). This will
            always yield zero or one result.
          schema:
            type: string
        - name: is_matched
          in: query
          description: >-
            Filter bill payments by match status. If true, only matched payments
            will be returned. If false, only unmatched payments will be
            returned. Bill payments are considered matched if they are matched
            directly, or if they are included in a vendor payout that is
            matched.
          schema:
            type: boolean
        - name: tag_key
          in: query
          description: >-
            Tag key to filter bill payments by. Must be used together with
            tag_values.
          required: false
          schema:
            type: string
        - name: tag_values
          in: query
          description: >-
            Comma-separated list of tag values to filter by. Must be used
            together with tag_key. Returns 404 if the tag key/value combination
            does not exist.
          required: false
          schema:
            type: string
        - name: vendor_id
          in: query
          description: >-
            Filter bill payments by vendor UUID. Returns payments tagged
            directly with this vendor, as well as payments allocated to bills
            associated with this vendor.
          required: false
          schema:
            type: string
            format: uuid
        - name: vendor_external_id
          in: query
          description: >-
            Filter bill payments by vendor external ID. Returns payments tagged
            directly with the vendor matching this external ID, as well as
            payments allocated to bills associated with that vendor.
          required: false
          schema:
            type: string
        - name: min_amount
          in: query
          description: >-
            Filter bill payments by minimum gross amount, in positive cents.
            Inclusive: only payments with a gross amount greater than or equal
            to this value are returned. Negative values are rejected.
          required: false
          schema:
            type: integer
            format: int64
        - name: max_amount
          in: query
          description: >-
            Filter bill payments by maximum gross amount, in positive cents.
            Inclusive: only payments with a gross amount less than or equal to
            this value are returned. Negative values are rejected.
          required: false
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiBillPayment'
                  meta:
                    $ref: '#/components/schemas/RequestMetadata'
                required:
                  - data
components:
  schemas:
    PaymentMethod:
      type: string
      enum:
        - CASH
        - CHECK
        - CREDIT_CARD
        - ACH
        - CREDIT_BALANCE
        - OTHER
      example: ACH
    ApiBillPayment:
      type: object
      properties:
        type:
          type: string
          description: Resource type. Value will be `com.layerfi.routers.ApiBillPayment`.
          example: com.layerfi.routers.ApiBillPayment
        id:
          type: string
          format: uuid
          description: Unique identifier for the payment.
        external_id:
          type: string
          nullable: true
          description: External ID for the payment.
        vendor:
          $ref: '#/components/schemas/ApiVendorData'
          nullable: true
          description: >-
            The vendor associated with this payment, if one has been set. May be
            present even when the payment is not allocated to any bill.
        at:
          type: string
          format: date-time
          description: When the payment was made.
        method:
          $ref: '#/components/schemas/PaymentMethod'
          description: Method used for payment.
        amount:
          type: integer
          format: int64
          description: Payment amount in cents.
        processor:
          type: string
          nullable: true
          description: Payment processor used.
        payment_clearing_account:
          $ref: '#/components/schemas/SingleApiChartAccount'
          description: >-
            The the ledger account to use for the payment (overrides the default
            determined by the payment method), if specified.
        imported_at:
          type: string
          format: date-time
          description: When the payment was imported.
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/ApiBillPaymentAllocation'
          description: How the payment is allocated across bills.
        transaction_tags:
          type: array
          items:
            $ref: '#/components/schemas/ApiTag'
          description: Tags associated with the payment.
        memo:
          type: string
          nullable: true
          description: >-
            Memo for any text you would like to associate with the bill payment
            (for example, to display to end users).
        metadata:
          $ref: '#/components/schemas/PlatformDefinedJson'
          nullable: true
          description: Arbitrary custom metadata in JSON format with a size limit of 1KB.
        reference_number:
          type: string
          nullable: true
          description: >-
            Any (typically user-visible) identifier you would like to associate
            with the bill payment. Can be used to filter when listing bill
            payments.
    RequestMetadata:
      type: object
      description: Request metadata. Present on paginated list responses.
      properties:
        type:
          type: string
          description: Metadata type discriminator. Value will be `request_metadata`.
          example: request_metadata
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
    ApiVendorData:
      type: object
      properties:
        type:
          type: string
          description: Resource type. Value will be `VendorData`.
          example: VendorData
        id:
          type: string
          format: uuid
          description: Unique identifier for the vendor.
        external_id:
          type: string
          description: >-
            Unique ID of the vendor in your system for linking purposes.
            **Idempotency key**.
        individual_name:
          type: string
          nullable: true
          description: Full name of the individual vendor or contact at a corporate vendor.
        company_name:
          type: string
          nullable: true
          description: Name of the company vendor.
        email:
          type: string
          nullable: true
          description: Email address of the vendor.
        mobile_phone:
          type: string
          nullable: true
          description: Mobile phone number of the vendor.
        office_phone:
          type: string
          nullable: true
          description: Office phone number of the vendor.
        address_string:
          type: string
          nullable: true
          description: Address of the vendor.
        memo:
          type: string
          nullable: true
          description: >-
            Memo for any text you would like to associate with the vendor (for
            example, to display to end users).
        status:
          type: string
          enum:
            - ACTIVE
            - ARCHIVED
          description: Status of the vendor.
          example: ACTIVE
        transaction_tags:
          type: array
          items:
            $ref: '#/components/schemas/ApiTag'
    SingleApiChartAccount:
      type: object
      properties:
        type:
          type: string
          description: Resource type. Value will be `Single_Chart_Account`.
          example: Single_Chart_Account
        id:
          $ref: '#/components/schemas/AccountIdentifier'
        name:
          type: string
          description: Name of the account.
          example: Current Assets
        account_number:
          type: string
          nullable: true
          description: Account number if configured.
          example: '4000'
        stable_name:
          $ref: '#/components/schemas/AccountStableName'
        normality:
          $ref: '#/components/schemas/BankTransactionDirection'
        account_type:
          $ref: '#/components/schemas/ApiLedgerAccountType'
        account_subtype:
          $ref: '#/components/schemas/ApiLedgerAccountSubtype'
      description: A single ledger account without nested children.
    ApiBillPaymentAllocation:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the allocation.
        bill_id:
          type: string
          format: uuid
          description: ID of the bill.
        payment_id:
          type: string
          format: uuid
          description: ID of the payment.
        amount:
          type: integer
          format: int64
          description: >-
            Amount of the payment allocated toward this bill, in cents. If this
            amount equals the full payment amount, the payment was fully
            allocated toward this bill. The amount cannot exceed the bill total.
        transaction_tags:
          type: array
          items:
            $ref: '#/components/schemas/ApiTag'
          description: Tags associated with the allocation.
        memo:
          type: string
          nullable: true
          description: >-
            Memo for any text you would like to associate with the bill payment
            allocation (for example, to display to end users).
        metadata:
          $ref: '#/components/schemas/PlatformDefinedJson'
          nullable: true
          description: Arbitrary custom metadata in JSON format with a size limit of 1KB.
        reference_number:
          type: string
          nullable: true
          description: >-
            Any (typically user-visible) identifier you would like to associate
            with the bill payment allocation.
    ApiTag:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID for the tag.
        key:
          type: string
          description: Key for the tag.
          example: ExampleTagKey
        dimension_display_name:
          type: string
          nullable: true
          description: Display name for the tag dimension.
        value:
          type: string
          description: Value for the tag.
          example: ExampleTagValue
        value_display_name:
          type: string
          nullable: true
          description: Display name for the tag value definition.
        dimension_id:
          type: string
          format: uuid
          description: ID of the tag dimension this tag belongs to.
        definition_id:
          type: string
          format: uuid
          description: ID of the tag value definition.
        archived_at:
          type: string
          format: date-time
          nullable: true
          description: When the tag was archived.
      required:
        - id
        - key
        - value
        - dimension_id
        - definition_id
    PlatformDefinedJson:
      type: object
      description: Arbitrary JSON data defined by the caller, with a 1KB size constraint.
      additionalProperties: true
      example:
        custom_field: value
        any valid json: below 1kb
        nested:
          meaning of life: 42
          array: []
    PaginationMetadata:
      type: object
      description: >-
        Cursor-based pagination metadata returned alongside paginated list
        responses.
      properties:
        sort_by:
          type: string
          nullable: true
          description: Field the result set is sorted by.
        sort_order:
          type: string
          enum:
            - ASC
            - DESC
          description: Sort direction applied to the result set.
          example: ASC
        cursor:
          type: string
          nullable: true
          description: >-
            Opaque cursor to pass as `pagination_cursor` to fetch the next page.
            Null when there are no further pages.
        has_more:
          type: boolean
          description: Whether additional pages are available after the current one.
        total_count:
          type: integer
          format: int64
          nullable: true
          description: Total number of records across all pages, when available.
      required:
        - sort_by
        - sort_order
        - cursor
        - has_more
    AccountIdentifier:
      oneOf:
        - $ref: '#/components/schemas/AccountId'
          description: ID of the account.
          title: Account ID
        - $ref: '#/components/schemas/AccountStableName'
          description: Stable name associated with the account.
          title: Account Stable Name
    AccountStableName:
      type: object
      required:
        - type
        - stable_name
      properties:
        type:
          type: string
          enum:
            - StableName
          description: Resource type. Value will be `StableName`.
          example: StableName
        stable_name:
          type: string
          example: CURRENT_ASSETS
          description: Stable name of the account.
    BankTransactionDirection:
      type: string
      enum:
        - CREDIT
        - DEBIT
      example: DEBIT
    ApiLedgerAccountType:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/LedgerAccountType'
          description: Type of the account.
        display_name:
          type: string
          description: Display name of the account type.
          example: Asset
    ApiLedgerAccountSubtype:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/LedgerAccountSubtype'
        display_name:
          type: string
          description: Display name of the account subtype.
          example: Current Assets
    AccountId:
      type: object
      required:
        - type
        - id
      properties:
        type:
          type: string
          enum:
            - AccountId
          description: Resource type. Value will be `AccountId`.
          example: AccountId
        id:
          type: string
          format: uuid
          description: ID of the account.
    LedgerAccountType:
      type: string
      enum:
        - ASSET
        - LIABILITY
        - EQUITY
        - REVENUE
        - EXPENSE
      example: ASSET
    LedgerAccountSubtype:
      type: string
      enum:
        - BANK_ACCOUNTS
        - ACCOUNTS_RECEIVABLE
        - INVENTORY
        - PAYMENT_PROCESSOR_CLEARING_ACCOUNT
        - FIXED_ASSET
        - ACCUMULATED_DEPRECIATION
        - CASH
        - UNDEPOSITED_FUNDS
        - CURRENT_ASSET
        - NON_CURRENT_ASSET
        - PREPAID_EXPENSES
        - DEVELOPMENT_COSTS
        - LOANS_RECEIVABLE
        - INTANGIBLE_ASSET
        - ACCOUNTS_PAYABLE
        - CREDIT_CARD
        - TAXES_PAYABLE
        - INCOME_TAXES_PAYABLE
        - SALES_TAXES_PAYABLE
        - OTHER_TAXES_PAYABLE
        - PAYROLL_TAXES_PAYABLE
        - UNEARNED_REVENUE
        - PAYROLL_LIABILITY
        - PAYROLL_CLEARING
        - LINE_OF_CREDIT
        - TIPS
        - REFUND_LIABILITIES
        - UNDEPOSITED_OUTFLOWS
        - OUTGOING_PAYMENT_CLEARING_ACCOUNT
        - OTHER_CURRENT_LIABILITY
        - LOANS_PAYABLE
        - NOTES_PAYABLE
        - SHAREHOLDER_LOAN
        - NON_CURRENT_LIABILITY
        - CONTRIBUTIONS
        - DISTRIBUTIONS
        - COMMON_STOCK
        - PREFERRED_STOCK
        - ADDITIONAL_PAID_IN_CAPITAL
        - RETAINED_EARNINGS
        - ACCUMULATED_ADJUSTMENTS
        - OPENING_BALANCE_EQUITY
        - OTHER_EQUITY
        - SALES
        - UNCATEGORIZED_REVENUE
        - RETURNS_ALLOWANCES
        - DIVIDEND_INCOME
        - INTEREST_INCOME
        - OTHER_INCOME
        - COGS
        - OPERATING_EXPENSES
        - PAYROLL
        - TAXES_LICENSES
        - UNCATEGORIZED_EXPENSE
        - CHARITABLE_CONTRIBUTIONS
        - LOAN_EXPENSES
        - FINANCE_COSTS
        - INTEREST_EXPENSES
        - DEPRECIATION
        - AMORTIZATION
        - BAD_DEBT
        - OTHER_EXPENSES
      example: BANK_ACCOUNTS
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````