> ## 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 vendor refunds > List all vendor refunds for a business with advanced filtering and search. **Features:** - Filter by status, refund type, vendor, date range, amount - Full-text search across reference numbers and descriptions - Sort by any field - Pagination support **Use Cases:** - View all pending refunds requiring processing - Find refunds for a specific vendor - Track refund history for accounting reconciliation - Monitor unallocated refunds **Available Filters:** - `status`: Filter by refund status (pending, partially_allocated, allocated, completed, cancelled). Comma-separated for multiple. - `refund_type`: Filter by type (overpayment, credit_balance, billing_error, etc.) - `vendor_id`: Filter by specific vendor UUID - `refund_date_start` / `refund_date_end`: Filter by date range (YYYY-MM-DD) - `min_amount` / `max_amount`: Filter by amount range (in cents) - `currency`: Filter by currency code (EUR, GBP, USD) - `is_fully_allocated`: Filter by allocation status (true/false) - `search`: Full-text search across reference_number, external_id, description, vendor name **Ordering:** - Default: `-refund_date,-created_at` (newest first) - Options: `refund_date`, `total_refunded_amount_cents`, `status`, `vendor__company_name` - Prefix with `-` for descending order ## OpenAPI ````yaml GET /v1/platform/businesses/{business_id}/vendor-refunds/ 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}/vendor-refunds/: get: tags: - Vendor Refunds summary: List vendor refunds description: |2- List all vendor refunds for a business with advanced filtering and search. **Features:** - Filter by status, refund type, vendor, date range, amount - Full-text search across reference numbers and descriptions - Sort by any field - Pagination support **Use Cases:** - View all pending refunds requiring processing - Find refunds for a specific vendor - Track refund history for accounting reconciliation - Monitor unallocated refunds **Available Filters:** - `status`: Filter by refund status (pending, partially_allocated, allocated, completed, cancelled). Comma-separated for multiple. - `refund_type`: Filter by type (overpayment, credit_balance, billing_error, etc.) - `vendor_id`: Filter by specific vendor UUID - `refund_date_start` / `refund_date_end`: Filter by date range (YYYY-MM-DD) - `min_amount` / `max_amount`: Filter by amount range (in cents) - `currency`: Filter by currency code (EUR, GBP, USD) - `is_fully_allocated`: Filter by allocation status (true/false) - `search`: Full-text search across reference_number, external_id, description, vendor name **Ordering:** - Default: `-refund_date,-created_at` (newest first) - Options: `refund_date`, `total_refunded_amount_cents`, `status`, `vendor__company_name` - Prefix with `-` for descending order operationId: list_vendor_refunds parameters: - in: path name: business_id schema: type: string pattern: ^[0-9a-f-]+$ required: true - in: query name: currency schema: type: string description: Filter by currency code (EUR, GBP, USD) - in: query name: external_id schema: type: string description: Filter by external ID (partial match) - in: query name: is_fully_allocated schema: type: boolean description: >- Filter by allocation status (true=fully allocated, false=has unallocated amount) - in: query name: max_amount schema: type: integer description: Maximum refund amount in cents - in: query name: min_amount schema: type: integer description: Minimum refund amount in cents - in: query name: ordering schema: type: string description: Order results by field (prefix with - for descending) - 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: reference_number schema: type: string description: Filter by reference number (partial match) - in: query name: refund_date_end schema: type: string format: date description: Filter refunds to this date (YYYY-MM-DD) - in: query name: refund_date_start schema: type: string format: date description: Filter refunds from this date (YYYY-MM-DD) - in: query name: refund_type schema: type: string x-spec-enum-id: 9e7c4f2adc5c33a3 enum: - billing_error - credit_balance - duplicate_payment - goods_return - other - overpayment - service_cancellation description: |- Filter by refund type * `overpayment` - Overpayment Refund * `credit_balance` - Credit Balance Refund * `duplicate_payment` - Duplicate Payment * `billing_error` - Billing Error * `goods_return` - Goods Return * `service_cancellation` - Service Cancellation * `other` - Other - in: query name: search schema: type: string description: >- Search across reference_number, external_id, description, vendor name - in: query name: status schema: type: string description: Filter by refund status (comma-separated for multiple) - in: query name: vendor_external_id schema: type: string description: Filter by vendor external ID - 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/PaginatedVendorRefundList' description: '' security: - BusinessScopedJWT: [] - PartnerJWT: [] - BasicAuth: [] - BearerUnscoped: [] - BearerBusinessScoped: [] components: schemas: PaginatedVendorRefundList: 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/VendorRefund' VendorRefund: type: object description: |- Comprehensive serializer for vendor refund responses. Includes all refund details plus related allocations and payments. properties: id: type: string format: uuid readOnly: true description: Unique vendor refund identifier vendor_id: type: string format: uuid readOnly: true description: UUID of the vendor who issued the refund vendor_name: type: string readOnly: true description: Vendor company name external_id: type: string description: Your external system identifier for idempotency maxLength: 255 refund_type: enum: - overpayment - credit_balance - duplicate_payment - billing_error - goods_return - service_cancellation - other type: string x-spec-enum-id: 9e7c4f2adc5c33a3 description: >- Refund type: overpayment, credit_balance, billing_error, goods_return, duplicate_payment, service_cancellation, other * `overpayment` - Overpayment Refund * `credit_balance` - Credit Balance Refund * `duplicate_payment` - Duplicate Payment * `billing_error` - Billing Error * `goods_return` - Goods Return * `service_cancellation` - Service Cancellation * `other` - Other reference_number: type: string description: External reference number for this refund maxLength: 100 refund_date: type: string format: date description: Date when refund was issued expected_completion_date: type: string format: date nullable: true description: Expected date for refund completion total_refunded_amount: type: integer description: Total refunded amount in cents readOnly: true allocated_amount: type: integer description: Total allocated amount in cents readOnly: true unallocated_amount: type: integer description: Remaining unallocated amount in cents readOnly: true currency: enum: - EUR - GBP - USD - SEK - NOK - DKK - ISK - MYR - SGD type: string x-spec-enum-id: 7e6a70e4775b3009 description: |- Refund currency (EUR, GBP, USD) * `EUR` - Euro * `GBP` - British Pound * `USD` - US Dollar * `SEK` - Swedish Krona * `NOK` - Norwegian Krone * `DKK` - Danish Krone * `ISK` - Icelandic Króna * `MYR` - Malaysian Ringgit * `SGD` - Singapore Dollar status: enum: - pending - partially_allocated - allocated - completed - cancelled type: string x-spec-enum-id: f9afcfd9cc5b0e7e description: >- Refund status: pending, partially_allocated, allocated, completed, cancelled (computed from allocations) * `pending` - Pending * `partially_allocated` - Partially Allocated * `allocated` - Allocated * `completed` - Completed * `cancelled` - Cancelled description: type: string description: Description of the refund reason or context memo: type: string description: Internal memo or notes reason: type: string description: Detailed explanation for the refund maxLength: 500 metadata: description: Custom key-value pairs allocations: type: array items: $ref: '#/components/schemas/VendorRefundAllocationResponse' readOnly: true vendor_refund_payments: type: array items: $ref: '#/components/schemas/VendorRefundPaymentResponse' readOnly: true document: allOf: - $ref: '#/components/schemas/DocumentFileUrl' readOnly: true description: Latest document linked to this vendor refund created_at: type: string format: date-time readOnly: true description: Refund creation timestamp updated_at: type: string format: date-time readOnly: true description: Last update timestamp required: - allocated_amount - allocations - created_at - document - id - total_refunded_amount - unallocated_amount - updated_at - vendor_id - vendor_name - vendor_refund_payments VendorRefundAllocationResponse: type: object description: Serializer for vendor refund allocation responses. All amounts in cents. properties: id: type: string format: uuid readOnly: true description: Unique allocation identifier allocation_type: enum: - bill - payment - credit type: string x-spec-enum-id: 9a3c37d0b190f26e description: |- Type of allocation: bill, payment, or credit * `bill` - Applied to Bill * `payment` - Refund of Payment * `credit` - Credit Balance amount: type: integer readOnly: true description: Allocated amount in cents bill_id: type: string format: uuid description: Bill ID if allocated to bill readOnly: true bill_number: type: string description: Bill number if allocated to bill readOnly: true bill_outstanding_balance_cents: type: integer description: Bill outstanding balance in cents if allocated to bill readOnly: true bill_payment_id: type: string format: uuid description: Bill payment ID if allocated to payment readOnly: true allocation_date: type: string format: date-time description: When allocation was created description: type: string description: Allocation description or notes maxLength: 500 metadata: description: Custom key-value pairs for allocation created_at: type: string format: date-time readOnly: true description: Allocation creation timestamp updated_at: type: string format: date-time readOnly: true description: Last update timestamp target_description: type: string readOnly: true description: Human-readable description of allocation target required: - amount - bill_id - bill_number - bill_outstanding_balance_cents - bill_payment_id - created_at - id - target_description - updated_at VendorRefundPaymentResponse: type: object description: Serializer for vendor refund payment responses. All amounts in cents. properties: id: type: string format: uuid readOnly: true description: Unique vendor refund payment identifier vendor_refund_id: type: string format: uuid readOnly: true description: ID of the vendor refund this payment belongs to payment_reference: type: string description: Your internal payment reference maxLength: 100 processor_payment_id: type: string description: External processor payment ID maxLength: 255 payment_date: type: string format: date description: Date when payment was made refunded_amount: type: integer description: Refunded amount in cents readOnly: true processing_fee: type: integer readOnly: true description: Processing fee in cents net_amount: type: integer readOnly: true description: Net amount after fees in cents payment_method: enum: - bank_transfer - ach - wire - check - credit_card - cash - other type: string x-spec-enum-id: 1cd9444edaf0ad8b description: >- Payment method: bank_transfer, ach, wire, check, credit_card, cash, other * `bank_transfer` - Bank Transfer * `ach` - ACH Transfer * `wire` - Wire Transfer * `check` - Check * `credit_card` - Credit Card Reversal * `cash` - Cash * `other` - Other processor: enum: - stripe - wise - paypal - bank_transfer - internal type: string x-spec-enum-id: c841362fdd1cad7c description: |- Payment processor: stripe, wise, paypal, bank_transfer, internal * `stripe` - Stripe * `wise` - Wise (TransferWise) * `paypal` - PayPal * `bank_transfer` - Direct Bank Transfer * `internal` - Internal Processing status: enum: - pending - processing - completed - failed - cancelled type: string x-spec-enum-id: 9c61eae888c009aa description: |- Payment status: pending, processing, completed, failed, cancelled * `pending` - Pending * `processing` - Processing * `completed` - Completed * `failed` - Failed * `cancelled` - Cancelled submitted_at: type: string format: date-time nullable: true description: When payment was submitted for processing completed_at: type: string format: date-time nullable: true description: When payment completed successfully failed_at: type: string format: date-time nullable: true description: When payment failed failure_reason: type: string description: Reason for payment failure description: type: string description: Payment description memo: type: string description: Internal memo metadata: description: Custom key-value pairs transaction_tags: description: Transaction tags for categorization reconciled_bank_transactions: type: array items: $ref: '#/components/schemas/EntityReconciliationDetail' readOnly: true description: Bank transactions this vendor refund payment is reconciled to created_at: type: string format: date-time readOnly: true description: Payment creation timestamp updated_at: type: string format: date-time readOnly: true description: Last update timestamp required: - created_at - id - net_amount - processing_fee - reconciled_bank_transactions - refunded_amount - updated_at - vendor_refund_id DocumentFileUrl: type: object description: Serializer for document file URL with metadata. properties: url: type: string format: uri description: Presigned URL for document download expires_in: type: integer description: Seconds until URL expires document_id: type: string format: uuid description: Document UUID file_name: type: string description: Original document filename file_size: type: integer description: File size in bytes mime_type: type: string description: MIME type of the document required: - document_id - expires_in - file_name - file_size - mime_type - url 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. ````