Skip to main content

List Bills

GET 
/api/bills/list

Paginated landed cost bills listing for the list view (/v2/purchases/bills). Lists every bill across all three link types (Purchase Order, Warehouse Transfer, Inbound Shipment) with computed totals, allocation status, and source (OCR vs manual).

Required scope: purchase-orders:read

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Uses Spatie QueryBuilder with grouped-filter (tree) support.

Authentication: Requires Bearer token. Scope: purchase-orders (read/write).

Pagination​

  • page — page number (default 1)
  • per_page — items per page (default 10)

Sorting​

sort — prefix with - for descending. Default: -created_at. Allowed sorts: id, invoice_number, invoice_date, supplier_name, supplier_id, link_type, link_reference, proration_strategy, currency_code, currency_rate, line_count, subtotal, tax_total, grand_total, allocated_amount, unallocated_amount, allocation_status, created_at, updated_at

filter[search] — searches Invoice Number (partial), Bill ID (exact), Supplier name, Bill line descriptions, and the linked document reference (PO number / transfer reference / shipment reference).

Advanced filters​

Advanced filters use the filter[{column}.{operator}]=value syntax. A bare filter[{column}]=value acts as an implicit is.

Text columns (operators: contains, does_not_contain, is, is_not, is_one_of, starts_with, does_not_start_with, ends_with, does_not_end_with, is_empty, is_not_empty):

  • invoice_number, proration_strategy, link_reference, currency_code
  • link_type — values: purchase_order, warehouse_transfer, inbound_shipment
  • source — values: ocr, manual
  • allocation_status — values: empty, unallocated, partial, allocated
  • supplier_name, line_description, line_nominal_code, cost_category (related-table text filters)
  • supplier_id, cost_category_id (ID-select filters, text-typed)

Numeric columns (operators: is, is_not, is_one_of, greater_than, less_than, greater_than_or_equal, less_than_or_equal, between, is_empty, is_not_empty):

  • id, currency_rate, subtotal, tax_total, total, grand_total, allocated_amount, unallocated_amount, line_count, line_quantity, line_amount
  • between takes two comma-separated values, e.g. filter[grand_total.between]=100,500

Date columns (operators: is, is_not, before, after, on_or_before, on_or_after, between, is_empty, is_not_empty, today, yesterday, tomorrow, past_week, past_month, past_year, next_week, next_month, next_year, days_ago, days_from_now, past_days, next_days):

  • invoice_date, created_at, updated_at
  • Dates use YYYY-MM-DD; between takes two comma-separated dates

Boolean filters:

  • filter[has_accounting_transaction]=true|false — whether an accounting transaction has been generated for the bill

Grouped filters (filter_groups)​

filter_groups — base64-encoded JSON tree supporting AND/OR conjunctions and nested groups. Takes precedence over flat filter[...] params when present.

JSON structure before encoding:

{
  "conjunction": "and",
  "children": [
    {"type": "condition", "condition": {"column": "allocation_status.is", "operator": "is", "value": "partial"}},
    {"type": "group", "group": {"conjunction": "or", "children": [...]}}
  ]
}

Response extras​

On top of Laravel's standard paginator JSON, the response includes:

  • unfiltered_total — total bill count with all filters cleared (for the export modal's "All records" label)
  • summary — tenant-currency stat card totals across the filtered result set: total_billed_tenant, total_allocated_tenant, total_unallocated_tenant, bill_count

Each bill includes documents_count (number of attached source documents) and document_filenames (their file names). Sortable by documents_count. Filter with filter[documents_count] (e.g. filter[documents_count.is]=0 for bills with no source document) or filter[document_filename] to match a source document's file name.

Request​

Responses​

OK

Response Headers
    Content-Type