Fieldmotion API Getting started

Invoices

Update credit-note data

POST /a/CreditNote_updateData

Replace the editable credit-note document data, recalculate totals and remaining balance, and refresh its historical customer snapshot.

When to use this endpoint

Use this to save the CRM2 Credit Notes editor or a status-only inline change. Omitted fields inherit current stored values.

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.

The tenant setting accounting_credit_notes must equal 1. Otherwise the handler returns {"error":"Credit Notes are not enabled for this account"}.

Users whose legacy crm_access mask contains bit 64 are denied. The handler does not enforce the CRM2 pageCreditNotes role permission, ownership, or department scope.

Parameters

ParameterTypeRequiredDescription
idPositive integer-compatibleYesActive credit-note ID.
Editable document fieldsSame as CreditNote_createDataNoAccepts the same customer/target, credited invoice, date, number, status, rows, totals, document references, accounting fields, form, and metadata aliases as create. Omitted values are taken from the current row.

Example request

$result = FM_api('CreditNote_updateData', [
	'id' => 311,
	'status' => 1,
	'reason' => 'Returned materials approved',
]);

Example response

{
  "ok": 1,
  "id": 311,
  "remaining": 15
}

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 credit note"}The ID is absent or soft-deleted.
{"error":"Credit Note total cannot be less than allocated amount"}The recalculated total is below the sum of allocations and refunds.
{"error":"Credit Note customer must match credited invoice customer"}The selected credited invoice and credit-note customer differ.
{"error":"Could not start Credit Note change. Please retry."}The database transaction could not begin.
{"error":"Credit Note change could not be saved. Please reload before retrying."}A database write or commit failed; the transaction is rolled back. For enablement, earlier completed invoice migrations remain committed.

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 same normalization, date fallback, status allowlist, total calculation, and customer/invoice checks as create apply. A blank submitted number remains blank; update does not allocate a new number.
  • Cancelled and Issued notes remain otherwise editable. There is no no-change response.
  • Remaining becomes max(0, total - all allocations/refunds). Changing credited_invoice_id does not move or delete existing allocation rows.

Side effects

  • Locks the active note while checking allocations, rewrites the complete editable document row, advances edit metadata, refreshes the historical customer/asset snapshot, invalidates the credit-note cache, and logs an update within a transaction. It does not update the credited invoice or fire a generic edit event.

See it in Fieldmotion

CRM1

No CRM1 credit-note editor was found.

CRM2

Saving the Credit Note editor and changing status inline on the Credit Notes list both call CreditNote_updateData.

Related endpoints