---
title: "List bill payments"
method: GET
path: "/v1/platform/businesses/{business_id}/bills/payments/"
tags: ["Bill Payments"]
---

# List bill payments

`GET /v1/platform/businesses/{business_id}/bills/payments/`

## Request

- Base URL: `https://docs.thredfi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.thredfi.com/v1/platform/businesses/{business_id}/bills/payments/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP basic
  - HTTP bearer
  - HTTP bearer

List all bill payments for a business with filtering and pagination.

        **Features:**
        - Filter by status (pending, processing, completed, failed, cancelled, returned)
        - Filter by payment method
        - Filter by vendor
        - Filter by bill
        - Filter by date range
        - Search by payment reference
        - Pagination support (default: 20 per page, max: 100)

        **Use Cases:**
        - View all pending payments requiring processing
        - Monitor payment status across all bills
        - Generate payment reports
        - Reconciliation dashboard

        **Available Filters:**
        - `status`: Filter by payment status
        - `payment_method`: Filter by payment method (bank_transfer, ach, wire, check, etc.)
        - `vendor_id`: Filter by vendor UUID
        - `bill_id`: Filter by bill UUID
        - `payment_date_start` / `payment_date_end`: Filter by date range
        - `search`: Search by payment_reference, check_number, processor_payment_id

## Path parameters

- `business_id` string, uuid, required

## Query parameters

- `bill_id` string, uuid
- `page` integer
- `page_size` integer
- `payment_date_end` string, date
- `payment_date_start` string, date
- `payment_method` string
- `search` string
- `status` string
- `vendor_id` string

## Response `200`

- PaginatedBillPaymentListList
  - `count` integer, required: Total number of items
  - `page_info` object, required
    - `total_count` integer, required: Total number of items (same as count)
    - `current_page` integer, required: Current page number (1-indexed)
    - `total_pages` integer, required: Total number of pages
    - `page_size` integer, required: Number of items per page
  - `results` BillPaymentList[], required
    - `id` string, uuid, required: Unique bill payment identifier
    - `vendor_id` string, uuid, required: Vendor receiving payment
    - `vendor_name` string, required: Vendor display name
    - `payment_reference` string, required: Payment reference
    - `payment_date` string, date, required: Payment date
    - `amount_cents` integer, required: Payment amount in cents
    - `currency` string, required: Payment currency
    - `payment_method` string, required: Payment method
    - `status` string, required: Payment status
    - `allocated_amount_cents` integer, required: Allocated amount in cents
    - `unallocated_amount_cents` integer, required: Unallocated amount in cents
    - `is_fully_allocated` boolean, required: Whether fully allocated to bills
    - `allocations` BillPaymentAllocation[], required: Bill allocations for this payment
      - `id` string, uuid, required: Unique allocation identifier
      - `bill_id` string, uuid, required: Bill this allocation applies to
      - `bill_number` string, required: Bill number
      - `vendor_bill_number` string, required: Vendor's bill number
      - `bill_status` string, required: Current bill status
      - `amount_cents` integer, required: Allocation amount in cents
      - `description` string: Allocation description
      - `allocation_date` string, date-time, required: When allocation was created
      - `created_at` string, date-time, required: Creation timestamp
    - `reconciled_bank_transactions` EntityReconciliationDetail[], required: Bank transactions this payment is reconciled to
      - `payment_type` string
      - `bank_transaction_id` string, uuid, required
      - `bank_transaction_date` string, date-time, required
      - `bank_transaction_amount_cents` integer, required
      - `bank_transaction_direction` string, required
      - `reconciled_amount_cents` integer, required
      - `reconciliation_link_id` string, uuid, required
      - `reconciled_at` string, date-time, required
      - `currency` string, required
      - `bank_account_name` string
      - `notes` string
    - `created_at` string, date-time, required: Creation timestamp
    - `updated_at` string, date-time, required: Update timestamp

## Other responses

- `400`: Validation errors in request data
- `401`: Authentication required - missing or invalid API key
- `403`: Permission denied - insufficient privileges
- `404`: Resource not found
- `409`: Conflict - resource already exists or invalid state transition
- `422`: Unprocessable entity - business logic validation failed
- `500`: Internal server error

---

[API](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api.md) - [All operations](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/revisions/0c1918254db3?raw)