Goods returns
Set one mapped return-header field
/a/GoodReturned_updateField
Set one mapped header field for selected IDs and return its previous database values.
When to use this endpoint
Use for a one-field mapped patch. Unlike updateData, this operation returns oldData on its changed path; it still does not validate business relationships or recalculate totals.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Session CSRF and account/IP restrictions still apply. These handlers add no goods-return, finance, department, owner or page-role permission check.
Records belong to the authenticated tenant. CRM1 shows this workflow when the employer features bit 262144 is enabled; CRM2 uses features2.goodsReturnedNotes. These are UI gates, not checks performed by these handlers.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
field | String | Yes | Exact writable header alias: cDate, supplierID, grnID, notes, totalNet, deliveryNet, deliveryTaxCode, deliverTax or customValues. id and lastEdited are rejected. |
val | Field-dependent value | Yes | Validated according to the alias: finite numeric amounts, whole integers, exact date/time or valid JSON/native JSON. Blank date/time/JSON is NULL; ordinary text is preserved. |
id / ids | Integer or native array | Yes | Target header IDs; id wins over ids. Integer-converted before selection. |
Example request
FM_api('GoodReturned_updateField', ['id'=>642, 'field'=>'notes', 'val'=>'Awaiting supplier credit']);Example response
{"ok":1,"oldData":[{"id":"642","notes":"Damaged packaging"}]}oldData uses physical database column names (for example delivery_tax, not deliverTax) and raw stored values. It includes all selected rows, not only rows whose value changed.
Errors and unusual responses
| Response | Condition |
|---|---|
{"error":"not logged in"} | No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs. |
{"error":"goods return write failed"} | A primary write or history insert failed; the transaction is rolled back. |
{"error":"goods return read failed"} | A required locking read failed; no changes commit. |
{"error":"goods return transaction failed"} | Starting/committing the tenant transaction failed. |
{"error":"goods return operation failed"} | Unexpected database/JSON processing failure; no changes commit. |
{"error":"missing or invalid parameter: field"} | field absent. |
{"error":"missing or invalid parameter: val"} | val key absent. |
{"error":"missing or invalid field"} | Unknown alias, id or lastEdited. |
{"error":"goods return record does not exist"} | Any target missing. |
{"ok":"1","warning":"no change required"} | Converted values unchanged. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Primary writes and history commit in one checked tenant transaction. A failed read, write or history insert rolls back the operation; individual bulk failures are not concealed.
- Primary IDs are immutable. Numeric amounts must be finite; integer fields must be whole 32-bit values. Quantities and stock/supplier IDs cannot be negative. Received-note references accept positive integers or legacy -1.
- Updates are partial patches; omitted values remain unchanged. Date/time strings must be exact YYYY-MM-DD HH:MM:SS, with blank/null stored as SQL NULL. customValues must be valid JSON/native JSON and replaces the complete value. Ordinary text "null" is preserved as text.
- Presentation readonly/hidden flags generally do not restrict header writes: dates, totals and delivery values remain writable. lastEdited is server-owned; supplied values are ignored.
- Header edits do not create lines, reconcile stock or recalculate totalNet. supplierID is not derived from grnID, and their relationship is not verified.
- A native ID array applies the same patch transactionally after every positive ID is found. Empty ID arrays succeed without writes. No optimistic lock is enforced.
- id wins over ids. Values are validated/converted before comparison. oldData uses physical column names and includes every selected row.
Side effects
- Changed writes advance last_edited, invalidate the table cache and atomically record field history. noRecord hides named field history; noRecordCustom hides named custom-key history. Neither skips persistence or removes history.
- No notification, PDF generation, accounting export or warehouse/container movement.
See it in Fieldmotion
CRM1
CRM1’s goods-return pages use the legacy GoodsReturned/GoodsReturnedNote calls instead of this mapped operation.
CRM2
No direct GoodReturned_updateField caller was found in the current CRM2 goods-return pages; their layout saves use GoodReturned_updateData. This endpoint is covered by its API regression.