Stock catalog fields and lookups
Save stock notes
/a/Stock_notesSet
Replace stock notes without trimming their whitespace.
When to use this endpoint
Use to save free-form stock notes. Always supply val; omission is rejected. Send an empty string when clearing notes.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. This handler requires both a user identity and tenant context; it adds no stock-page, finance or administrator permission check.
All queries use the authenticated tenant. API signing and session CSRF checks still apply; see Getting started.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer-compatible string | Yes | Stock ID, converted with intval; use a positive tenant-local ID. |
val | String | Yes | Required non-null scalar, normalized to string without trimming. Empty string clears notes; whitespace/newlines are preserved. Arrays and objects are rejected. |
Example request
$result = FM_api('Stock_notesSet', ['id'=>'1042', 'val'=>'Store in a dry cabinet.']);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":"missing or invalid parameter: id"} | Missing/nonpositive id. |
{"error":"Stock item does not exist"} | No row for the ID. |
{"ok":1,"warning":"no change needed"} | Stored notes strictly equal val; no write or event. |
{"error":"stock catalog write failed"} | A primary write or required history insert fails; the transaction rolls back. |
{"error":"stock catalog read failed"} | A checked read fails; a normalization or write transaction is rolled back. |
{"error":"stock catalog transaction failed"} | Transaction start or commit fails; no success is returned. |
{"error":"stock catalog operation failed"} | Unexpected database/runtime failure during the transaction. |
{"error":"missing or invalid parameter: val"} | val is absent/null or non-scalar. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Locks the target non-deleted stock row; archived stock remains editable. Missing/deleted stock returns Stock item does not exist.
- Strict comparison of stored notes and string-normalized input makes an unchanged save a no-op.
- The checked UPDATE and field history commit together before Stock_edit. No notes-specific tenant setting is consulted.
- No direct mobile caller was found in the current app JavaScript or
m/wwwintermediary. The app receives stock throughsyncDownloads, which selects non-deleted stock by edit timestamp; these calls are not the app synchronization protocol.
Side effects
- On change, writes notes, server last_edited and edited_uuid=Stock_notesSet and checked field history in one transaction; invalidates stocks cache.
- Stock_edit runs after commit. No stock movement; a follow-up failure may return committed-success warning.
See it in Fieldmotion
CRM1
Open Stock and click the notes icon. Save sends Stock_notesSet with id and textarea val; the dialog uses the table’s existing notes instead of calling Stock_notesGet.
CRM2
The Stocks notes cell calls the shared mapped updateData flow with table Stock and notes; it does not call this narrow setter.
Related endpoints
Stock_notesGetreads just the stored notes.