Invoices

Count invoices by collection status, and total the money

Answers 'how many, and how much' in ONE request. Returns counts per collection_status, outstanding and collected money per currency, and the customers owed the most (by_customer, capped by customer_limit), over the filters listInvoices accepts (all but invoice_number). Use this instead of paging every invoice and adding it up: collection_status is derived from Finero's own payment record and is not something a caller can compute from the fields it receives, and money must never be summed or ranked across currencies, so by_customer ranks within each. Exact at any workspace size: the counts come from an indexed column, so nothing is capped and nothing is sampled. Every filter listInvoices accepts except invoice_number works here too — pair due_after with due_before to select whole invoices by their earliest collectible due date. For installment-level aging use the Aging operations; an invoice can span multiple aging buckets.

Available to admin and readonly API keys (no side effects).

get/v1/invoices/summary

Request

  • Base URL: https://api.getfinero.com/functions/v1/api
  • URL: https://api.getfinero.com/functions/v1/api/v1/invoices/summary
  • Auth: HTTP bearer

Query parameters

collection_status'paid' | 'open' | 'inactive'

Count and total only invoices with this collection status. NOT derivable from the unfiltered response: by_collection_status already gives the counts, but by_currency aggregates money across every status — so 'how much is still open, per currency' needs this filter. An inactive invoice can carry a real balance it will never collect, and summing across statuses buries that in the same number.

currencystring

Filter by ISO 4217 currency code.

connection_idstring uuid

Filter by ERP connection.

updated_sincestring date-time

Only invoices updated at or after this ISO 8601 timestamp. updated_at moves when the invoice's own data changes (an ERP delivery, a retirement, an edit), NOT when only Finero's collection state does (collection_status, collection_outstanding, amount_collected, erp_push_state, has_active_payment_link): poll GET /v1/payments?confirmed_since= for collections. The bound INCLUDES its own timestamp, so polling with the newest updated_at you have seen returns that row again every time - expected, and not a change.

customer_idstring uuid

Only count invoices for this customer, by the stable customer.id. One call gives that customer's whole exposure, per currency — the safe alternative to paging the book and grouping by name.

erp_push_state'held' | 'pending' | 'processing' | 'posted' | 'failed'

Only count invoices whose payment write-back to the ERP is in this state. erp_push_state=failed answers 'how much money has Finero collected that the ERP does not know about?' in one call.

has_active_payment_linkboolean

Only count invoices with (true) or without (false) an active Finero payment link — the same filter the list accepts, so the money behind an unlinked worklist is one call.

due_beforestring date

Only invoices whose collection_due_date is on or before this date (YYYY-MM-DD), INCLUSIVE. The overdue worklist is due_before=<today> with collection_status=open. FILTERS ON collection_due_date, so an invoice that has none is excluded — and one has none precisely when nothing on it is collectible, which is also when it can still owe money. Date bands therefore never sum to the whole book: check a total against a call with no date filter, never against the bands. amount_collected under ANY date filter is PARTIAL and never a collected total: a fully paid invoice has no collection_due_date so its collections drop out, while a partly collected OPEN invoice keeps its own and stays in. Ask with no date filter for what was collected.

due_afterstring date

Only invoices whose collection_due_date is on or after this date (YYYY-MM-DD), INCLUSIVE. Combine with due_before for one aging bucket — but because BOTH ends include their own date, adjacent bands must not share a boundary: use due_before=X then due_after=<X plus one day>, or every invoice dated exactly X is counted twice and the profile sums to more than the book. Every collection_due_date exclusion and the partial-amount_collected caveat described on due_before applies here identically.

customer_limitinteger

How many by_customer rows to return (default 25, max 100), drawn evenly across currencies so a short list never omits one. Read by_customer_total to know whether the cap hid rows.

Response

Success

totalinteger required

Invoices matching the filters. An exact count, never an estimate — and the number to trust for 'how many are there'.

inactive_nothing_to_collectinteger required

The subset of inactive with nothing left to collect — settled outside Finero, cancelled, a draft, empty, a credit, or no longer present in your ERP. inactive minus this is the count with money STUCK on it: owed, and not collectible right now. This is Finero's own answer (its collection_outstanding at or below zero, which is also the case for an invoice not finalised in your ERP), not the ERP's balance, so it stays correct while the ERP lags.

by_customer_totalinteger required

How many (customer, currency) rows matched in total. When it exceeds the length of by_customer, the list was capped by customer_limit — raise it, or narrow the filters.

Changes

No recorded changes to this operation across all 1 revision of this API.