Goods returns
Create a mapped return-note header
/a/GoodReturned_createData
Create a goods-return header without changing stock.
When to use this endpoint
Use for the mapped CRM2 header flow. Supply a goods-received reference and optional header values; this call does not accept or process the legacy rows return-line list.
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 |
|---|---|---|---|
supplierID | Integer | No | Non-negative whole supplier ID; no supplier existence/deletion or received-note ownership check. |
grnID | Integer | On create | Whole positive goods-received note ID or legacy -1. Required on header creation; optional on updates/line creation. No received-note existence or supplier ownership check. |
notes | String | No | Header notes; not appended or merged. |
totalNet | Number | No | Stored total_net, converted with floatval. Writable despite readonly UI metadata; not recalculated from lines. |
deliveryNet | Number | No | Stored delivery_net, converted with floatval. Writable despite readonly UI metadata. |
deliveryTaxCode | String | No | Stored delivery_taxcode; no tax-category existence or rate validation. |
deliverTax | Number | No | Exact mapped name for delivery_tax. This is a tax amount, not a percentage. deliveryTax is not a mapped alias. |
customValues | JSON text or native object | No | Replaces the whole custom_values value; creation defaults to {}. Native arrays/objects are JSON-encoded. No schema validation or per-key merge. |
cDate | Date/time string | No | Exact YYYY-MM-DD HH:MM:SS without timezone conversion. Defaults to server now on creation. Blank/null becomes SQL NULL; writable despite UI readonly metadata. |
lastEdited | Date/time string | No | Server-owned edit time; supplied values are ignored. Creation and changed updates set last_edited to server date/time. |
noRecord | Native array | No | Native field-alias list whose history is marked hidden on create/update; does not skip persistence/history or grant authorization. |
noRecordCustom | Native array | No | Custom-value keys whose generated history metadata is marked hidden. Does not prevent the saved value, history creation or authorization checks. |
Example request
FM_api('GoodReturned_createData', ['supplierID'=>84, 'grnID'=>531, 'notes'=>'Damaged packaging']);Example response
{"ok":1,"id":"642"}id is a checked database insert ID, normally a numeric string; failed inserts return an error, not ok with an invalid ID.
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: grnID"} | Header create requires a whole positive reference or legacy -1. |
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.
- Creation ignores id; timestamps default to server now, header customValues defaults to {}, and other omissions use database defaults. Metadata-only line creation still allows omitted parent/quantity.
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
CRM2’s goods-return layouts use the goodReturned mapping in php/Layout/_map.php: create/read/update are GoodReturned_createData, GoodReturned_getLayoutDetails and GoodReturned_updateData. The table uses GoodsReturned_getDataTable; its delete action calls GoodReturned_delete.