Skip to main content

List Purchase Invoices

GET 
/api/purchase-invoices

Get a paginated list of purchase invoices with filtering and sorting.

Required scope: purchase-orders:read

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

Authentication: Requires Bearer token.

Filters use the filter[field] syntax. Text filters support operators like is, is_not, contains, starts_with, ends_with, is_empty, is_not_empty. Numeric filters support is, is_not, greater_than, less_than, between. Datetime filters support date range comparisons.

Allowed sorts: id, purchase_invoice_date, due_date, other_date, supplier_invoice_number, status, purchase_order_id, supplier_id, created_at, updated_at, purchase_order_number, supplier_name, line_item_count, attachments_count.

Each row includes attachments_count (number of attached documents) and attachment_filenames (their file names). Filter with filter[attachments_count] (e.g. =0 for invoices with no documents) or filter[attachment_filename] (match a document's file name). Default sort: -id (newest first). Default: excludes archived invoices unless filter[archived] is provided.

The response also includes unfiltered_total, the count of rows in the base scope before any user filters are applied — used by the frontend to show export totals.

Each invoice includes is_provisional — true for committed-spend bills auto-created at PO submission (they mirror the PO's unbilled remainder and are removed once fully billed). Filter them with filter[is_provisional] (only / hide / all).

Each row includes due_date_source (derived, manual, none) and needs_shipment_link — true when the invoice's payment term dates it per shipment but no shipment is linked yet, so the due date shown is the order-level fallback. Filter on it with filter[needs_shipment_link.is] (1 / 0). Link a shipment with Link Inbound Shipment to Invoice or Auto-Link Inbound Shipments to settle the date.

Approval policy: Filter with filter[payment_approval_status] and filter[awaiting_my_approval]=1. Each row adds approval — the approval-policy summary for this bill's payment: policy_enabled (false when no policy governs bill payments; the other fields are then null/empty), request_id, status, reason, tier_name of the latest approval request, waiting_on (names of users who can act now), can_approve_directly (whether you can approve it now; on a document with no request yet, whether its amount falls within your limit) and blocked_reason. Full timeline: GET /api/approval-requests/for/bill_payment/{id}. Bills add approved_amount / approved_amount_base (the amount a completed payment approval authorized, in bill and base currency) and, on single-bill responses, approved_remaining (how much of it payments have not yet used; null on list rows). This is the payment approval, separate from the bill's own approval_status.

Request​

Responses​

OK