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

# Update bill

> Update bill via PUT.

**Line Items**: If `line_items` is provided, ALL existing line items are deleted and replaced. If omitted, line items remain unchanged.



## OpenAPI

````yaml PUT /v1/platform/businesses/{business_id}/bills/{bill_id}/
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/{bill_id}/:
    put:
      tags:
        - Bills
      summary: Update bill
      description: >-
        Update bill via PUT.


        **Line Items**: If `line_items` is provided, ALL existing line items are
        deleted and replaced. If omitted, line items remain unchanged.
      operationId: update_bill
      parameters:
        - in: path
          name: bill_id
          schema:
            type: string
            format: uuid
          description: A UUID string identifying this bill.
          required: true
        - in: path
          name: business_id
          schema:
            type: string
            pattern: ^[0-9a-f-]+$
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillUpdateAPIRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BillUpdateAPIRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BillUpdateAPIRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bill'
          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:
        - PartnerJWT: []
        - BusinessScopedJWT: []
        - BasicAuth: []
        - BearerUnscoped: []
        - BearerBusinessScoped: []
components:
  schemas:
    BillUpdateAPIRequest:
      type: object
      description: >-
        Bill update serializer. Applies partial updates to a Bill, and replaces
        line items if provided.
      properties:
        vendor_id:
          type: string
          format: uuid
          nullable: true
          description: Updated vendor UUID (cannot change if bill has payments)
        vendor_external_id:
          type: string
          description: Updated vendor external ID
        external_id:
          type: string
          description: Updated external identifier (must remain unique)
        bill_number:
          type: string
          description: Updated internal bill number
        vendor_bill_number:
          type: string
          description: Updated vendor invoice number
        purchase_order_number:
          type: string
          description: Updated PO number
        memo:
          type: string
          description: Updated description or notes
        reference_numbers:
          type: array
          items:
            type: string
            minLength: 1
          description: Updated reference numbers array
        attachment_urls:
          type: array
          items:
            type: string
            minLength: 1
          description: Updated document URLs array
        received_at:
          type: string
          format: date-time
          nullable: true
          description: Updated received date/time
        due_at:
          type: string
          format: date-time
          nullable: true
          description: Updated payment due date/time
        approved_at:
          type: string
          format: date-time
          nullable: true
          description: Date/time bill was approved (triggers journal entry creation)
        currency:
          enum:
            - EUR
            - GBP
            - USD
            - SEK
            - NOK
            - DKK
            - ISK
            - MYR
            - SGD
            - ''
          type: string
          x-spec-enum-id: 7e6a70e4775b3009
          description: |-
            Updated currency (cannot change if bill has financial data)

            * `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
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/BillUpdateLineItemRequest'
          description: Updated line items array (replaces all existing)
        bill_terms:
          type: string
          description: Updated payment terms (NET_30, NET_60, DUE_ON_RECEIPT)
        document:
          allOf:
            - $ref: '#/components/schemas/BillDocumentUploadRequest'
          writeOnly: true
          description: Optional document upload
    Bill:
      type: object
      description: >-
        Main bill serializer for list/fetch responses, aligned with existing API
        style
      properties:
        type:
          type: string
          readOnly: true
          description: Always 'BillData' for type discrimination
        id:
          type: string
          format: uuid
          readOnly: true
        business_id:
          type: string
          format: uuid
          readOnly: true
        external_id:
          type: string
        status:
          type: string
          readOnly: true
          description: 'Bill status: received, partially_paid, paid, voided'
        terms:
          type: string
          readOnly: true
          description: Payment terms (NET_30, NET_60, DUE_ON_RECEIPT, etc.)
        issue_date:
          type: string
          format: date
          description: Date the bill was issued by vendor (from bill_date)
          readOnly: true
        received_at:
          type: string
          format: date-time
          readOnly: true
          description: Date/time bill was received
        due_at:
          type: string
          format: date-time
          readOnly: true
          description: Payment due date/time
        paid_at:
          type: string
          format: date-time
          readOnly: true
          description: Full payment completion date/time
        voided_at:
          type: string
          format: date-time
          readOnly: true
          description: Void action timestamp
        is_overdue:
          type: boolean
          description: True if bill is past due date and has outstanding balance
          example: false
          readOnly: true
        bill_number:
          type: string
        vendor_bill_number:
          type: string
        purchase_order_number:
          type: string
        memo:
          type: string
        reference_numbers: {}
        attachment_urls: {}
        metadata: {}
        currency:
          type: string
          readOnly: true
        vendor:
          allOf:
            - $ref: '#/components/schemas/Vendor'
          readOnly: true
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/BillLineItem'
          readOnly: true
        bill_payment_allocations:
          type: array
          items:
            $ref: '#/components/schemas/BillPaymentAllocationSummary'
          readOnly: true
          description: Payment allocations for this bill
        vendor_credit_allocations:
          type: array
          items:
            $ref: '#/components/schemas/VendorCreditAllocationSummary'
          readOnly: true
          description: Vendor credit note allocations for this bill
        vendor_refund_allocations:
          type: array
          items:
            $ref: '#/components/schemas/VendorRefundAllocationSummary'
          readOnly: true
          description: Vendor refund allocations for this bill
        additional_sales_taxes:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalSalesTax'
          readOnly: true
          description: Additional tax entries not included in line items
        additional_sales_taxes_total:
          type: integer
          description: Total additional sales taxes in cents
          readOnly: true
        subtotal:
          type: integer
          description: Subtotal amount in cents before taxes
          readOnly: true
        total_amount:
          type: integer
          description: Total bill amount in cents including taxes
          readOnly: true
        outstanding_balance:
          type: integer
          description: Outstanding balance in cents
          readOnly: true
        paid_by_bank_payments:
          type: integer
          description: Amount paid via bank payments in cents (completed only)
          readOnly: true
        paid_by_credits:
          type: integer
          description: Amount paid via vendor credit notes in cents
          readOnly: true
        needs_reconciliation:
          type: boolean
          description: True if has unreconciled bank payments
          readOnly: true
        document:
          allOf:
            - $ref: '#/components/schemas/DocumentFileUrl'
          readOnly: true
          description: Latest document with presigned URL
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
      required:
        - additional_sales_taxes
        - additional_sales_taxes_total
        - bill_payment_allocations
        - business_id
        - created_at
        - currency
        - document
        - due_at
        - id
        - is_overdue
        - issue_date
        - line_items
        - needs_reconciliation
        - outstanding_balance
        - paid_at
        - paid_by_bank_payments
        - paid_by_credits
        - received_at
        - status
        - subtotal
        - terms
        - total_amount
        - type
        - updated_at
        - vendor
        - vendor_credit_allocations
        - vendor_refund_allocations
        - voided_at
    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
    BillUpdateLineItemRequest:
      type: object
      description: >-
        Line item input for bill update requests (full replacement of line items
        when provided)
      properties:
        description:
          type: string
        account_identifier:
          nullable: true
          description: Expense account identifier, e.g., {"type":"AccountId","id":"..."}
        product:
          type: string
        quantity:
          type: number
          format: double
        unit_price:
          type: integer
          description: Unit price in cents
        sales_taxes:
          type: array
          items:
            type: object
            additionalProperties: {}
      required:
        - quantity
        - unit_price
    BillDocumentUploadRequest:
      type: object
      description: |-
        Bill specific document upload payload.

        Inherits from BaseFileUploadSerializer pattern for file validation.
      properties:
        file:
          type: string
          format: binary
          writeOnly: true
        document_type:
          type: string
          default: purchase_invoice
        upload_source:
          type: string
        metadata: {}
        tags: {}
    Vendor:
      type: object
      description: Serializer for vendor objects returned by the vendors list endpoint
      properties:
        type:
          type: string
          readOnly: true
          description: Resource type (always 'VendorData')
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique vendor identifier
        external_id:
          type: string
          description: Your unique identifier for this vendor (used for idempotency)
          maxLength: 255
        individual_name:
          type: string
          description: Vendor individual name (for sole traders/freelancers)
          maxLength: 255
        company_name:
          type: string
          description: Registered company name (for limited companies)
          maxLength: 255
        email:
          type: string
          format: email
          description: Primary email address for vendor communications
          maxLength: 254
        mobile_phone:
          type: string
          readOnly: true
          description: Mobile phone number (E.164 format, e.g., +44 7700 900123)
        office_phone:
          type: string
          readOnly: true
          description: Office phone number (E.164 format, e.g., +44 20 7946 0958)
        address_string:
          type: string
          readOnly: true
          description: Full formatted address (read-only, auto-generated)
        memo:
          type: string
          readOnly: true
          description: Internal notes or description for this vendor
        status:
          type: string
          readOnly: true
          description: Vendor status (ACTIVE, INACTIVE, ARCHIVED, BLOCKED)
        transaction_tags:
          type: array
          items: {}
          readOnly: true
          description: List of tags for categorization
        documents:
          type: array
          items:
            $ref: '#/components/schemas/DocumentFileUrl'
          readOnly: true
          description: All documents linked to this vendor with presigned URLs
      required:
        - address_string
        - documents
        - id
        - memo
        - mobile_phone
        - office_phone
        - status
        - transaction_tags
        - type
    BillLineItem:
      type: object
      description: >-
        Serializer for bill line items in listing responses.


        Performance Note:

        - Accesses bill.id and bill.currency which require the bill relationship

        - When used in BillSerializer (via many=True), the parent bill is
        already loaded

        - For standalone usage, ensure queryset uses: .select_related('bill')

        - For nested usage in Bill list, ensure:
        .prefetch_related(Prefetch('line_items',
        queryset=BillLineItem.objects.select_related('bill')))
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        bill_id:
          type: string
          format: uuid
          readOnly: true
        account_identifier:
          allOf:
            - $ref: '#/components/schemas/AccountIdentifier'
          nullable: true
          readOnly: true
        description:
          type: string
        product:
          type: string
        currency:
          type: string
          readOnly: true
        unit_price:
          type: integer
          description: Unit price in cents
          readOnly: true
        quantity:
          type: number
          format: float
          description: Return quantity as float
          readOnly: true
        subtotal:
          type: integer
          description: Subtotal before taxes 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
        tax_rate:
          type: number
          format: float
          readOnly: true
          description: Tax rate as a percentage (e.g., 20.0 for 20%)
      required:
        - account_identifier
        - bill_id
        - currency
        - id
        - quantity
        - sales_taxes_total
        - subtotal
        - tax_rate
        - total_amount
        - unit_price
    BillPaymentAllocationSummary:
      type: object
      description: Payment allocation summary for bill detail view.
      properties:
        amount_cents:
          type: integer
        payment_date:
          type: string
          format: date
        payment_method:
          type: string
        bill_payment_id:
          type: string
          format: uuid
      required:
        - amount_cents
        - bill_payment_id
        - payment_date
        - payment_method
    VendorCreditAllocationSummary:
      type: object
      description: >-
        Credit allocation summary for bill detail view - shows vendor credits
        applied to this bill.
      properties:
        amount_cents:
          type: integer
        applied_at:
          type: string
          format: date-time
        vendor_credit_id:
          type: string
          format: uuid
        vendor_credit_number:
          type: string
      required:
        - amount_cents
        - applied_at
        - vendor_credit_id
    VendorRefundAllocationSummary:
      type: object
      description: >-
        Vendor refund allocation summary for bill detail view - shows vendor
        refunds allocated to this bill.
      properties:
        vendor_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
        - vendor_refund_id
    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
    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.

````