Stock catalog fields and lookups
Save the stock description
/a/Stock_descriptionSet
Replace a stock item’s description with trimmed text.
When to use this endpoint
Use to save the full stock description after editing it. Omit val only when deliberately clearing the field.
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 | Omitted or integer zero is rejected; negative values pass validation but still need an existing row. |
val | String | No | Defaults to empty text. Leading/trailing whitespace is trimmed; blank clears the description. No handler length limit. |
Example request
$result = FM_api('Stock_descriptionSet', ['id'=>'1042', 'val'=>'Replacement filter cartridge']);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 id parameter given"} | Missing/zero id. |
{"error":"Stock item does not exist"} | No stock row matches the ID. |
{"ok":"1","warning":"no change needed"} | Stored description loosely equals the trimmed input; 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"} | Present val is 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
- Reads and locks a non-deleted row; archived stock remains editable. Missing or deleted IDs return Stock item does not exist.
- An omitted val clears existing text. Scalar values are string-normalized then trimmed; arrays/objects are rejected. Strict string comparison determines no-op. A changed write returns numeric ok; the legacy no-op shape retains string ok.
- Primary write and field history are checked in one transaction. Stock_edit runs after commit and sees the saved description. No role/feature or tenant description 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, atomically writes description, server last_edited, edited_uuid=Stock_descriptionSet and checked field history; invalidates stocks cache. No physical quantity change.
- Configured Stock_edit listeners run once after commit. Tenant event configuration determines integration or communication effects; a thrown follow-up failure yields committed-success warning.
See it in Fieldmotion
CRM1
On Stock, click a description cell and change its textarea. CRM1 sends id and the complete val, although the table preview keeps only the first 100 characters.
CRM2
No direct CRM2 browser caller was found for this exact endpoint; the Stocks module uses mapped Stock reads and writes.
Related endpoints
Stock_descriptionGetloads the complete stored value.