Fieldmotion API Getting started

Invoices

Create a credit note

POST /a/CreditNote_createData

Create a standalone credit note with normalized line items, calculated totals, customer snapshot, numbering, and accounting metadata.

When to use this endpoint

Use this from the CRM2 Credit Notes editor. To credit a particular invoice, select it first so the editor uses the same customer and submits creditedInvoiceId.

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
customer / customerID / customer_idPicker object / integerYesCustomer or asset-backed customer ID. A customer array with id/type takes precedence; JSON text is not decoded for this parameter. The record itself is not independently checked.
customerType / customer_typeInteger-compatibleNoDefaults to 0. Must match the credited invoice’s customer type when an invoice is selected.
targetId / target_id; targetType / target_typeIntegersNoOptional billed target, normally the selected asset. Target existence is not validated.
creditedInvoiceId / credited_invoice_idPositive integer-compatibleNoActive invoice being credited. Its customer ID/type must exactly match the credit note.
cdate / num / statusDate string / string / integerNoInvalid or blank dates silently become the server date. Blank number uses tenant numbering. Status defaults to -1 Draft and may be -1, 1 Issued, or 3 Cancelled.
rows / rowsData / widgetTableInvoiceArray or JSON array stringNoLine items; the first supplied alias wins. Empty lines are removed, positional legacy rows are normalized, and missing net/tax/gross values can be derived.
pandp / pandpVat / pandp_vatNumeric-compatibleNoDelivery net amount and its tax amount.
discount / discountVat / discount_vatNumeric-compatibleNoInvoice-wide discount net and tax amounts subtracted from totals.
notes / reason / docNo / orderNoStringsNoDocument text and references. Snake-case aliases doc_no/order_no are also accepted.
nominal_code / nominalCode; taxCodeId / tax_code_id; formId / form_idMixedNoHeader accounting and report-form selections. Related records are not validated.
metaObject or JSON object stringNoStored as JSON. Blank, malformed, scalar, or non-object input becomes an empty array.

Example request

$credit = FM_api('CreditNote_createData', [
	'customerID' => 1042,
	'creditedInvoiceId' => 981,
	'cdate' => '2026-10-02',
	'status' => -1,
	'reason' => 'Returned materials',
	'rows' => json_encode([[
		'description' => 'Returned part', 'qty' => 1, 'price' => 40, 'net' => 40, 'gross' => 48, 'taxpc' => 20,
	]]),
]);

Example response

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

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":"Credit Note customer must match credited invoice customer"}The credited invoice’s customer ID/type differs.
{"error":"Credit Note total cannot be negative"}Calculated gross total is below zero.
{"error":"missing or invalid parameter: status"}Status is outside Draft, Issued, or Cancelled.

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

Behaviour and edge cases

  • Gross total is the sum of normalized row gross values plus delivery and delivery tax, less discount and discount tax. Net total prefers each row’s discountOverall over net.
  • Number method 1 increments the greatest active number by length/lexical order, 2 leaves it blank, and other values increment the last-created active number. An empty history begins with credit-note-number-prefix or CN-, followed by 1.
  • The customer snapshot uses address history at the credit-note date.

Side effects

  • Inserts the credit note, stores its initial remaining balance equal to total, snapshots customer/asset details, and writes a create activity entry. It does not send mail, create allocations, fire a generic edit event, or update the credited invoice.

See it in Fieldmotion

CRM1

No CRM1 credit-note creation flow was found.

CRM2

Open Credit Notes and choose Create. The custom editor submits CreditNote_createData; any allocation rows are sent separately only after the note has an ID.

Related endpoints