> ## Documentation Index > Fetch the complete documentation index at: https://docs.thredfi.com/llms.txt > Use this file to discover all available pages before exploring further. # List bill payments > 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 ## OpenAPI ````yaml GET /v1/platform/businesses/{business_id}/bills/payments/ openapi: 3.0.3 info: title: Thredfi Accounting Platform API version: 1.0.0 description: >- Comprehensive API for accounting, invoice management, open banking, and intelligence services. servers: [] security: [] paths: /v1/platform/businesses/{business_id}/bills/payments/: get: tags: - Bill Payments summary: List bill payments description: |2- 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 operationId: list_bill_payments parameters: - in: query name: bill_id schema: type: string format: uuid description: Filter by bill UUID - in: path name: business_id schema: type: string format: uuid description: Business UUID required: true - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer - in: query name: payment_date_end schema: type: string format: date description: Filter payments to this date (YYYY-MM-DD) - in: query name: payment_date_start schema: type: string format: date description: Filter payments from this date (YYYY-MM-DD) - in: query name: payment_method schema: type: string description: Filter by payment method - in: query name: search schema: type: string description: Search by payment reference, check number, or processor payment ID - in: query name: status schema: type: string description: Filter by payment status - in: query name: vendor_id schema: type: string description: >- Filter by vendor ID (supports comma-separated UUIDs for multiple vendors) responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedBillPaymentListList' description: '' '400': content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' description: Validation errors in request data '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication required - missing or invalid API key '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission denied - insufficient privileges '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Resource not found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict - resource already exists or invalid state transition '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable entity - business logic validation failed '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal server error security: - BusinessScopedJWT: [] - PartnerJWT: [] - BasicAuth: [] - BearerUnscoped: [] - BearerBusinessScoped: [] components: schemas: PaginatedBillPaymentListList: type: object required: - count - page_info - results properties: count: type: integer example: 123 description: Total number of items page_info: type: object example: total_count: 123 current_page: 1 total_pages: 7 page_size: 20 required: - total_count - current_page - total_pages - page_size properties: total_count: type: integer example: 123 description: Total number of items (same as count) current_page: type: integer example: 1 description: Current page number (1-indexed) total_pages: type: integer example: 7 description: Total number of pages page_size: type: integer example: 20 description: Number of items per page results: type: array items: $ref: '#/components/schemas/BillPaymentList' ValidationErrorResponse: type: object description: Validation error response with field-specific errors properties: error_code: type: string description: Error code (e.g., 'validation_error') message: type: string nullable: true description: Human-readable error message detail: type: object additionalProperties: {} description: Contains field_errors and additional context request_id: type: string description: Request ID for tracing required: - detail - error_code - message ErrorResponse: type: object description: Standard error response format properties: error_code: type: string description: Error code for programmatic handling message: type: string nullable: true description: Human-readable error message detail: type: object additionalProperties: {} description: Additional error details including field_errors and debug info request_id: type: string description: Request ID for tracing required: - error_code - message BillPaymentList: type: object description: Serializer for listing bill payments. All amounts in cents. properties: id: type: string format: uuid readOnly: true description: Unique bill payment identifier vendor_id: type: string format: uuid readOnly: true description: Vendor receiving payment vendor_name: type: string readOnly: true description: Vendor display name payment_reference: type: string readOnly: true description: Payment reference payment_date: type: string format: date readOnly: true description: Payment date amount_cents: type: integer readOnly: true description: Payment amount in cents currency: type: string readOnly: true description: Payment currency payment_method: type: string readOnly: true description: Payment method status: type: string readOnly: true description: Payment status allocated_amount_cents: type: integer readOnly: true description: Allocated amount in cents unallocated_amount_cents: type: integer readOnly: true description: Unallocated amount in cents is_fully_allocated: type: boolean readOnly: true description: Whether fully allocated to bills allocations: type: array items: $ref: '#/components/schemas/BillPaymentAllocation' readOnly: true description: Bill allocations for this payment reconciled_bank_transactions: type: array items: $ref: '#/components/schemas/EntityReconciliationDetail' readOnly: true description: Bank transactions this payment is reconciled to created_at: type: string format: date-time readOnly: true description: Creation timestamp updated_at: type: string format: date-time readOnly: true description: Update timestamp required: - allocated_amount_cents - allocations - amount_cents - created_at - currency - id - is_fully_allocated - payment_date - payment_method - payment_reference - reconciled_bank_transactions - status - unallocated_amount_cents - updated_at - vendor_id - vendor_name BillPaymentAllocation: type: object description: Serializer for bill payment allocation details. All amounts in cents. properties: id: type: string format: uuid readOnly: true description: Unique allocation identifier bill_id: type: string format: uuid description: Bill this allocation applies to bill_number: type: string readOnly: true description: Bill number vendor_bill_number: type: string readOnly: true description: Vendor's bill number bill_status: type: string description: Current bill status readOnly: true amount_cents: type: integer description: Allocation amount in cents description: type: string description: Allocation description allocation_date: type: string format: date-time readOnly: true description: When allocation was created created_at: type: string format: date-time readOnly: true description: Creation timestamp required: - allocation_date - amount_cents - bill_id - bill_number - bill_status - created_at - id - vendor_bill_number EntityReconciliationDetail: type: object description: >- Which bank transaction an entity (invoice/bill payment) is reconciled to. properties: payment_type: type: string bank_transaction_id: type: string format: uuid bank_transaction_date: type: string format: date-time bank_transaction_amount_cents: type: integer bank_transaction_direction: type: string reconciled_amount_cents: type: integer reconciliation_link_id: type: string format: uuid reconciled_at: type: string format: date-time currency: type: string bank_account_name: type: string notes: type: string required: - bank_transaction_amount_cents - bank_transaction_date - bank_transaction_direction - bank_transaction_id - currency - reconciled_amount_cents - reconciled_at - reconciliation_link_id securitySchemes: BusinessScopedJWT: type: http scheme: bearer bearerFormat: JWT description: >- Business-scoped JWT token. Token payload includes `business_id` to automatically scope requests. Format: `Bearer ` **Use this for**: Business-specific operations where the business context is embedded in the token. PartnerJWT: type: http scheme: bearer bearerFormat: JWT description: >- Partner-level JWT token (unscoped). Token payload includes `partner_id`. Business access is validated via partner ownership. Format: `Bearer ` **Use this for**: Multi-business operations where the business_id is specified in the URL and partner has access to multiple businesses. BasicAuth: type: http scheme: basic description: >- Basic authentication for OAuth2 token endpoint. Use partner_uuid:api_key as username:password. Example: Authorization: Basic base64(partner_uuid:api_key) BearerUnscoped: type: http scheme: bearer bearerFormat: JWT description: >- Partner (unscoped) JWT Bearer token. Obtain via POST /v1/platform/oauth2/token with Basic auth (partner_uuid:api_key). Use header: Authorization: Bearer {access_token} BearerBusinessScoped: type: http scheme: bearer bearerFormat: JWT description: >- Business-scoped JWT Bearer token. Obtain via POST /v1/platform/{business_id}/oauth2/token/ using a partner Bearer token. Only valid for endpoints whose URL contains that business_id. ````