> ## 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 invoices

> List all invoices for a business with comprehensive filtering options and standardized pagination



## OpenAPI

````yaml GET /v1/platform/businesses/{business_id}/invoices/
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}/invoices/:
    get:
      tags:
        - Invoices
      summary: List invoices
      description: >-
        List all invoices for a business with comprehensive filtering options
        and standardized pagination
      operationId: list_invoices
      parameters:
        - in: path
          name: business_id
          schema:
            type: string
            format: uuid
          description: Business UUID provided by Thred (unique identifier for the business)
          required: true
        - in: query
          name: customer_external_id
          schema:
            type: string
          description: Filter by customer external ID
        - in: query
          name: customer_id
          schema:
            type: string
          description: >-
            Filter by customer ID (supports comma-separated UUIDs for multiple
            customers)
        - in: query
          name: due_at_end
          schema:
            type: string
            format: date-time
          description: Filter invoices due before this date (ISO format)
        - in: query
          name: due_at_start
          schema:
            type: string
            format: date-time
          description: Filter invoices due after this date (ISO format)
        - in: query
          name: max_amount
          schema:
            type: integer
          description: Maximum amount in cents
        - in: query
          name: memo
          schema:
            type: string
          description: Filter by exact memo text
        - in: query
          name: memo_contains
          schema:
            type: string
          description: Filter by memo containing text
        - in: query
          name: min_amount
          schema:
            type: integer
          description: Minimum amount in cents
        - in: query
          name: page
          schema:
            type: integer
          description: 'Page number (default: 1)'
        - in: query
          name: page_size
          schema:
            type: integer
          description: 'Items per page (default: 20, max: 100)'
        - in: query
          name: reference_numbers
          schema:
            type: string
          description: Filter by reference numbers (comma-separated)
        - in: query
          name: search
          schema:
            type: string
        - in: query
          name: sent_at_end
          schema:
            type: string
            format: date-time
          description: Filter invoices sent before this date (ISO format)
        - in: query
          name: sent_at_start
          schema:
            type: string
            format: date-time
          description: Filter invoices sent after this date (ISO format)
        - in: query
          name: sort
          schema:
            type: string
            default: '-imported_at'
          description: >-
            Sort order. Values: imported_at, -imported_at, updated_at,
            -updated_at (prefix with - for descending)
        - in: query
          name: status
          schema:
            type: string
          description: >-
            Filter by invoice status (comma-separated). Values: sent, paid,
            partially_paid, voided, refunded
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedInvoiceList'
          description: ''
      security:
        - PartnerJWT: []
        - BusinessScopedJWT: []
        - BasicAuth: []
        - BearerUnscoped: []
        - BearerBusinessScoped: []
components:
  schemas:
    PaginatedInvoiceList:
      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/Invoice'
    Invoice:
      type: object
      description: |-
        Invoice serializer for API responses
        All monetary amounts are returned in cents
      properties:
        type:
          type: string
          description: Resource type identifier
          readOnly: true
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique invoice identifier
        business_id:
          type: string
          format: uuid
          readOnly: true
          description: Business this invoice belongs to
        external_id:
          type: string
          description: External system identifier
        status:
          type: string
          enum:
            - DRAFT
            - SENT
            - PAID
            - PARTIALLY_PAID
            - OVERDUE
            - CANCELLED
            - REFUNDED
          example: SENT
          readOnly: true
          description: Invoice status in uppercase format
        sent_at:
          type: string
          format: date-time
          readOnly: true
          description: When the invoice was sent to customer
        due_at:
          type: string
          format: date-time
          description: When payment is due (ISO timestamp)
          readOnly: true
        paid_at:
          type: string
          format: date-time
          readOnly: true
          description: When the invoice was fully paid
        voided_at:
          type: string
          format: date-time
          nullable: true
          readOnly: true
          description: When the invoice was voided (always null - we use cancelled status)
        is_overdue:
          type: boolean
          description: True if invoice is past due date and has outstanding balance
          example: false
          readOnly: true
        invoice_number:
          type: string
          description: Invoice number for display and reference
          maxLength: 100
        invoice_type:
          enum:
            - invoice
            - receipt
          type: string
          x-spec-enum-id: 026df2e18581a7be
          readOnly: true
          description: |-
            Type of invoice: invoice or receipt

            * `invoice` - Invoice
            * `receipt` - Receipt
        currency:
          type: string
          readOnly: true
          description: ISO 4217 currency code (e.g., EUR, GBP, USD)
          maxLength: 3
        memo:
          type: string
          description: Invoice description or memo
        customer:
          allOf:
            - $ref: '#/components/schemas/Customer'
          readOnly: true
          description: Customer information
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceLineItem'
          readOnly: true
          description: Array of invoice line items
        subtotal:
          type: integer
          description: Subtotal amount in cents before taxes
          readOnly: true
        additional_discount:
          type: integer
          description: Additional invoice-level discount in cents
          readOnly: true
        additional_sales_taxes:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalSalesTax'
          readOnly: true
          description: Additional sales taxes array
        additional_sales_taxes_total:
          type: integer
          description: Total additional sales taxes in cents
          readOnly: true
        tips:
          type: integer
          description: Tips amount in cents
          readOnly: true
        tips_account:
          type: string
          nullable: true
          readOnly: true
          description: Tips account information
        total_amount:
          type: integer
          description: Total invoice amount in cents including taxes
          readOnly: true
        outstanding_balance:
          type: integer
          description: Outstanding balance in cents
          readOnly: true
        payment_allocations:
          type: array
          items:
            $ref: '#/components/schemas/InvoicePaymentAllocationSummary'
          readOnly: true
          description: Array of payment allocations
        credit_allocations:
          type: array
          items:
            $ref: '#/components/schemas/CustomerCreditAllocationSummary'
          readOnly: true
          description: Array of customer credit note allocations
        refund_allocations:
          type: array
          items:
            $ref: '#/components/schemas/RefundAllocationSummary'
          readOnly: true
          description: Array of refund allocations
        write_offs:
          type: array
          items:
            $ref: '#/components/schemas/WriteOffSummary'
          readOnly: true
          description: Array of write-offs on this invoice
        document:
          allOf:
            - $ref: '#/components/schemas/DocumentFileUrl'
          readOnly: true
          description: Latest invoice document file with presigned URL
        imported_at:
          type: string
          format: date-time
          readOnly: true
          description: When the invoice was imported/created
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: When the invoice was last updated
      required:
        - additional_discount
        - additional_sales_taxes
        - additional_sales_taxes_total
        - business_id
        - credit_allocations
        - currency
        - customer
        - document
        - due_at
        - id
        - imported_at
        - invoice_number
        - invoice_type
        - is_overdue
        - line_items
        - outstanding_balance
        - paid_at
        - payment_allocations
        - refund_allocations
        - sent_at
        - status
        - subtotal
        - tips
        - tips_account
        - total_amount
        - type
        - updated_at
        - voided_at
        - write_offs
    Customer:
      type: object
      description: |-
        Main customer serializer for customer API endpoints
        Returns customer information with comprehensive details
        Used for both list and detail responses
      properties:
        type:
          type: string
          description: Type identifier (always 'CustomerData')
          readOnly: true
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the customer
        external_id:
          type: string
          description: Your unique identifier for this customer (used for idempotency)
        reference_number:
          type: string
          description: Customer reference number for invoices and statements
        individual_name:
          type: string
          description: >-
            Individual/contact person name (required if company_name not
            provided)
        company_name:
          type: string
          description: Registered company name (required if individual_name not provided)
        display_name:
          type: string
          readOnly: true
          description: >-
            Display name for the customer (auto-generated from company_name or
            individual_name)
        email:
          type: string
          format: email
          description: Primary email address for the customer
        mobile_phone:
          type: string
          description: Mobile phone number
        office_phone:
          type: string
          description: Office/landline phone number
        address_line1:
          type: string
          description: Street address line 1
        address_line2:
          type: string
          description: Street address line 2 (building, suite, etc.)
        city:
          type: string
          description: City or town
        state_county:
          type: string
          description: State, county, or region
        postal_code:
          type: string
          description: Postal/ZIP code
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
        full_address:
          type: string
          readOnly: true
          description: Complete formatted address with all fields
        address_string:
          type: string
          readOnly: true
          description: Single-line formatted address
        vat_number:
          type: string
          description: 'VAT registration number (for UK: GB followed by 9 digits)'
        tax_exempt:
          type: boolean
          description: Whether customer is exempt from tax/VAT
        status:
          type: string
          description: Customer status (ACTIVE or ARCHIVED)
          readOnly: true
        is_active:
          type: boolean
          readOnly: true
          description: Whether the customer is active (read-only)
        is_archived:
          type: boolean
          readOnly: true
          description: Whether the customer is archived (read-only)
        transaction_tags:
          type: array
          items: {}
          description: Array of tags for categorization and filtering
        notes:
          type: string
          description: Internal notes about the customer
        metadata:
          description: Custom JSON metadata for partner-specific data
        payment_terms_days:
          type: integer
          description: Number of days for payment terms (e.g., 30 for Net 30)
        credit_limit:
          type: integer
          description: Maximum credit limit in cents (e.g., 100000 for £1,000)
          readOnly: true
        credit_limit_cents:
          type: integer
          description: Maximum credit limit in cents (e.g., 100000 for £1,000)
        outstanding_balance:
          type: integer
          description: Current outstanding balance in cents (read-only, computed)
          readOnly: true
        documents:
          type: array
          items:
            $ref: '#/components/schemas/DocumentFileUrl'
          readOnly: true
          description: >-
            All documents linked to this customer with presigned URLs (retrieve
            only, not in list)
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: Date and time when the customer was created
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: Date and time when the customer was last updated
        archived_at:
          type: string
          format: date-time
          readOnly: true
          description: Date and time when the customer was archived (null if active)
      required:
        - address_line1
        - address_line2
        - address_string
        - archived_at
        - city
        - company_name
        - country
        - created_at
        - credit_limit
        - credit_limit_cents
        - display_name
        - documents
        - email
        - external_id
        - full_address
        - id
        - individual_name
        - is_active
        - is_archived
        - metadata
        - mobile_phone
        - notes
        - office_phone
        - outstanding_balance
        - payment_terms_days
        - postal_code
        - reference_number
        - state_county
        - status
        - tax_exempt
        - transaction_tags
        - type
        - updated_at
        - vat_number
    InvoiceLineItem:
      type: object
      description: |-
        Serializer for invoice line items
        All monetary amounts are returned in cents
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the line item
        external_id:
          type: string
          description: External system identifier for this line item
        invoice_id:
          type: string
          format: uuid
          readOnly: true
          description: Invoice this line item belongs to
        account_identifier:
          allOf:
            - $ref: '#/components/schemas/AccountIdentifier'
          nullable: true
          readOnly: true
          description: Account identifier for revenue posting
        description:
          type: string
          description: Description of the product or service
          maxLength: 500
        product:
          type: string
          description: Product code or SKU
        unit_price:
          type: integer
          description: Unit price in cents
          readOnly: true
        quantity:
          type: number
          format: float
          description: Quantity of items
          readOnly: true
        subtotal:
          type: integer
          description: Subtotal before taxes in cents
          readOnly: true
        discount_amount:
          type: integer
          description: Discount amount in cents
          readOnly: true
        sales_taxes_total:
          type: integer
          description: Total tax amount in cents
          readOnly: true
        total_amount:
          type: integer
          description: Total amount including taxes in cents
          readOnly: true
      required:
        - account_identifier
        - description
        - discount_amount
        - id
        - invoice_id
        - quantity
        - sales_taxes_total
        - subtotal
        - total_amount
        - unit_price
    AdditionalSalesTax:
      type: object
      description: Additional sales tax entry (invoice/bill level taxes).
      properties:
        tax_account:
          nullable: true
          description: Tax account identifier (optional)
        amount:
          type: integer
          description: Tax amount in cents
        rate:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
          description: Tax rate percentage (e.g., 20.00 for 20%)
        name:
          type: string
          description: Tax name (e.g., 'VAT', 'GST')
      required:
        - amount
    InvoicePaymentAllocationSummary:
      type: object
      description: Payment allocation summary for invoice detail view.
      properties:
        amount_cents:
          type: integer
        payment_date:
          type: string
          format: date
        payment_method:
          type: string
        payment_id:
          type: string
          format: uuid
      required:
        - amount_cents
        - payment_date
        - payment_id
        - payment_method
    CustomerCreditAllocationSummary:
      type: object
      description: >-
        Credit allocation summary for invoice detail view - shows credits
        applied to this invoice.
      properties:
        amount_cents:
          type: integer
        applied_at:
          type: string
          format: date-time
        credit_note_id:
          type: string
          format: uuid
        reference_number:
          type: string
      required:
        - amount_cents
        - applied_at
        - credit_note_id
    RefundAllocationSummary:
      type: object
      description: >-
        Refund allocation summary for invoice detail view - shows refunds
        allocated to this invoice.
      properties:
        refund_id:
          type: string
          format: uuid
        reference_number:
          type: string
        amount_cents:
          type: integer
        allocated_at:
          type: string
          format: date-time
      required:
        - allocated_at
        - amount_cents
        - refund_id
    WriteOffSummary:
      type: object
      description: Write-off summary for invoice detail view.
      properties:
        write_off_id:
          type: string
          format: uuid
        amount_cents:
          type: integer
        reason:
          type: string
        status:
          type: string
        write_off_at:
          type: string
          format: date-time
      required:
        - amount_cents
        - reason
        - status
        - write_off_at
        - write_off_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
    AccountIdentifier:
      type: object
      description: Standard account identifier format used across the API.
      properties:
        type:
          type: string
          default: AccountId
          description: Account identifier type (always 'AccountId')
        id:
          type: string
          format: uuid
          description: Account UUID
      required:
        - id
  securitySchemes:
    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
        <your-jwt-token>`


        **Use this for**: Multi-business operations where the business_id is
        specified in the URL and partner has access to multiple businesses.
    BusinessScopedJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Business-scoped JWT token. Token payload includes `business_id` to
        automatically scope requests. Format: `Bearer <your-jwt-token>`


        **Use this for**: Business-specific operations where the business
        context is embedded in the token.
    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.

````