Invoices
List invoice payments
/a/InvoicePayments_list
List raw invoice-payment history for one invoice or, when unfiltered, the entire authenticated tenant.
When to use this endpoint
Use this after loading an invoice to display its payment-history tab. Always pass invoice_id for ordinary UI/integration use.
Authentication and permissions
The request must authenticate with signed API-key fields or a logged-in CRM session and is scoped to the authenticated tenant.
Users whose legacy crm_access mask contains bit 64 are denied. The handler performs no additional invoice-page, ownership, or department permission check.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
invoice_id | Integer-compatible | No | Exact invoice ID filter. If the key is present, even blank/nonnumeric input becomes invoice_id=0. If omitted, payments for every invoice in the tenant are returned. |
fields | Array or JSON array string | No | Allowlisted fields: id, invoice_id, amt, user_id, cdate, type, meta. Unknown values are silently omitted. Missing/malformed/empty input defaults to id, invoice_id, cdate, amt. |
Example request
$payments = FM_api('InvoicePayments_list', [
'invoice_id' => 981,
'fields' => json_encode(['cdate', 'amt', 'user_id', 'meta']),
]);Example response
[
{"cdate":"2026-10-02 14:30:00","amt":"25","user_id":"77","meta":"{}"}
]Errors and unusual responses
| Response | Condition |
|---|---|
{"error":"not logged in"} | No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- The result is unpaginated and unordered. Payment
metaremains JSON text. - The endpoint does not join or validate invoices, so payments remain queryable for missing or soft-deleted invoices.
- Omitting
invoice_idcan return the tenant’s complete payment table.
See it in Fieldmotion
CRM1
Open an invoice’s History of Changes dialog and select Payments. CRM1 requests this route with invoice ID and the date/amount/user/metadata fields.
CRM2
Open an invoice Payment dialog. CRM2 caches the same invoice-scoped field selection after recording payments through Invoice_pay.
Related endpoints
Invoice_payappends a positive payment and may mark the invoice Paid.Invoice_getsupplies current paid/total values.