Goods returns
Replace legacy return-note notes
/a/GoodsReturnedNote_setNotes
Replace a return header’s notes and advance its edit timestamp.
When to use this endpoint
CRM1 saves the return-note notes box with this call. This is a header text edit, not a line-description update or an append-only notes operation.
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 |
|---|---|---|---|
id | Integer-converted value | Yes | Positive whole header ID; target must exist. |
notes | String | Yes | Complete replacement text. Empty string clears notes; omission/null produces an error. No append/merge or trimming. |
Example request
FM_api('GoodsReturnedNote_setNotes', ['id'=>642,'notes'=>'Awaiting supplier credit']);Example response
{"ok":1}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":"no return note ID provided"} | id absent. |
{"error":"no notes provided"} | notes absent/null. |
{"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":"goods return record does not exist"} | Header missing; no patch commits. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Replaces notes without append/trim. Positive whole existing header ID required; ordinary text "null" is preserved.
- Checked persistence/history commit transactionally; failed writes/audits roll back and missing targets return an error.
- Changed values advance last_edited; unchanged values return ok without writing. Concurrent edits have no optimistic lock.
Side effects
- Invalidates goods_returned cache and commits checked field history with changed values. No tax-rate calculation, stock movement, export, notification or PDF generation.
See it in Fieldmotion
CRM1
pageGoodsReturnedNote uses this on notes edits.
CRM2
CRM2’s notes field is saved through Layout_setValue → GoodReturned_updateData instead.