Fieldmotion API Getting started

Invoices

Record an invoice payment

POST /a/Invoice_pay

Record a positive invoice payment and automatically mark balanced invoices and their linked quote as paid.

When to use this endpoint

Use this to append a payment rather than directly replacing the invoice’s accumulated paid value.

Authentication and permissions

The request must use a logged-in CRM session or valid signed API credentials and is scoped to that tenant.

Users whose legacy crm_access mask contains bit 64 receive {"error":"no permission to access api"}. No record-owner check is made.

Parameters

ParameterTypeRequiredDescription
idPositive integerYesActive invoice ID.
amtPositive numeric-compatibleYesPayment amount; zero and negative values are rejected.

Example request

$result = FM_api('Invoice_pay', ['id' => 981, 'amt' => '25.00']);

Example response

{
  "ok": 1
}

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"error":"missing or invalid parameter: amt"}The amount is missing, zero, negative, or not numeric-compatible.
{"error":"invoice does not exist"}The invoice is absent or deleted.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Payments accumulate without an idempotency key. Retrying after an uncertain response can duplicate a payment.
  • When accumulated payments reach or exceed total, status becomes Paid and paid_date becomes the server date. Overpayment is retained.
  • With Workflow enabled, the payment, invoice change, and workflow transitions are transactional. Without it, the legacy operations are not wrapped in a transaction.

Side effects

  • Inserts an invoice_payments row and activity log. Balancing the invoice may mark a quote linked through the first direct job as paid, record invoice/quote workflow transitions, send the configured paid notification, remove overdue scheduling, and fire Invoice_edit.

See it in Fieldmotion

CRM1

The main Invoices page Payment dialog submits this route.

CRM2

Open an invoice Payment dialog and choose Add; the list refreshes payments through InvoicePayments_list.

Related endpoints