Fieldmotion API Getting started

Invoices

Set an invoice status

POST /a/Invoice_setStatus

Transition an invoice status and perform the payment, synchronization, notification, quote, and Workflow effects tied to that status.

When to use this endpoint

Use this instead of a raw status update whenever invoice lifecycle effects must run.

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.
valInteger-compatibleYes-1 Draft, 0 Quoted, 1 Invoiced, 2 Paid, 3 Cancelled, or legacy 4 Credit Note. Other integers are stored and logged as Unknown.

Example request

$result = FM_api('Invoice_setStatus', ['id' => 981, 'val' => 1]);

Example response

{
  "ok": 1,
  "id": 981
}

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":"no such invoice"}The invoice is absent or deleted.
{"error":"Credit Notes are enabled. Use the Credit Notes page instead of invoice status Credit Note."}Status 4 is requested while real credit notes are enabled.

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

Behaviour and edge cases

  • Leaving Draft assigns a number if blank using the greatest active number, independently of the configurable Invoice_getNumberNext selection policy.
  • Paid balances paid to total, inserts the difference as a payment, sets the server-date paid date, and may mark a quote linked through the first direct job Paid.
  • Cancelled removes tenant invoice sync links and global upload-queue entries. Other transitions do not restore those links.
  • With Workflow enabled, invoice/quote writes and transition records are transactional. An unchanged status returns warning: no change necessary.

Side effects

  • Writes activity history, fires Invoice_edit, records Workflow transitions when enabled, sends configured Paid mail, and removes or creates overdue scheduling according to the new status.

See it in Fieldmotion

CRM1

Invoice, Job Invoice, Customer Invoice, Asset Invoice, bulk edit, and Send Email workflows use this route.

CRM2

Invoice lists, multi-edit, and Send Email call this route. Mapped Invoice_updateData/updateField delegate here when Workflow is enabled.

Related endpoints