Fieldmotion API Getting started

Invoices

Add a credit-note allocation

POST /a/CreditNote_addAllocation

Apply part of a credit note to an invoice balance or record it as a refund, reducing the credit note’s remaining balance.

When to use this endpoint

Use this after saving a credit note and loading its current allocations. Invoice allocations and refunds share the same credit-note balance, but only invoice allocations reduce the calculated outstanding invoice balance.

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
credit_note_id / creditNoteIdPositive integer-compatibleYesActive credit note. The snake-case name takes precedence.
invoice_id / invoiceIdPositive integer-compatibleFor allocationActive invoice receiving the credit. Ignored and stored as 0 for a refund.
amt / amountPositive numeric-compatibleYesRounded to two decimals. It may not exceed the credit note’s current remaining balance; an allocation may not exceed the invoice total minus payments and earlier credit allocations.
typeStringNoDefaults to allocation; accepted values are allocation and refund.
noteStringNoTrimmed text stored inside allocation metadata.

Example request

$allocation = FM_api('CreditNote_addAllocation', [
	'credit_note_id' => 311,
	'invoice_id' => 981,
	'amt' => '25.00',
	'type' => 'allocation',
	'note' => 'Applied to INV-981',
]);

Example response

{
  "ok": 1,
  "id": 72,
  "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":"cannot allocate a cancelled Credit Note"}The credit note status is Cancelled (3).
{"error":"allocation exceeds Credit Note remaining balance"}The amount exceeds the credit note’s remaining value.
{"error":"allocation exceeds invoice balance"}The invoice is missing/deleted, already settled, or has less outstanding balance than the requested allocation.
{"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

  • A refund never references an invoice.
  • Invoice balance is calculated as max(0, total - paid - prior credit allocations). Refunds do not reduce that invoice balance.
  • The operation has no idempotency key; retrying after an uncertain response can duplicate the allocation.

Side effects

  • Inserts a credit_note_allocations row with the current user and server time, recalculates credit_notes.remaining, advances credit-note edit metadata, and writes credit-note activity history.
  • The balance checks lock the credit note and, for an invoice allocation, the receiving invoice. The allocation and remaining update commit together; a failed write rolls back the change. Concurrent requests cannot both spend the same remaining balance. A successful retry still creates a new allocation: this is not an idempotency mechanism.

See it in Fieldmotion

CRM1

No CRM1 credit-note screen or production caller was found.

CRM2

On Credit Notes, edit a saved note and add an Allocation or Refund row, then save. Filter Network requests for CreditNote_addAllocation. New credit notes must be saved before allocations can be added.

Related endpoints