Work areas and stock categories
Patch a mapped stock category
/a/StockCategory_updateData
Change selected mapped category fields and keep affected stock category summaries synchronized.
When to use this endpoint
StockCategory_getRequestedDetails supplies mapped values for editing. This call patches supplied fields rather than requiring a full legacy save payload.
Categories organize stock membership and parent/child navigation; these calls do not transfer physical stock or change quantities. Select the legacy or mapped API that matches your field names.
Authentication and permissions
Authenticate using signed API-key fields or a logged-in CRM session. All object queries use the authenticated tenant. The handler has no additional page, role or feature check unless stated below.
Sign numeric request values as strings, including nested native arrays; only JSON-encode parameters that explicitly accept JSON text. See Getting started.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Positive integer | Yes | One positive integer ID of an active tenant-local record; arrays, negative numbers and SQL-like strings are rejected. |
name | String | No | Trimmed nonempty category name, maximum 80 characters; duplicate names are allowed. |
parentID | Nonnegative integer | No | 0 is root; supplied positive parent must be active and cannot be this category, a descendant or part of a cyclic ancestor chain. Creation defaults to 0; omitted updates preserve the parent. |
stock | CSV, JSON array text or native array | No | Replaces the full membership. Normalizes positive integers, deduplicates and sorts numerically; empty clears membership. Every retained positive ID must identify non-deleted tenant stock. |
lastEdited / noRecord / noRecordCustom | Ignored | No | Server timestamps and checked field-history recording cannot be overridden. |
Example request
$result = FM_api('StockCategory_updateData', ['id'=>'1042','name'=>'Parts','stock'=>'71,72']);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"} | Not one positive integer. |
{"error":"stock category does not exist"} | No active category matches. |
{"error":"missing or invalid parameter: name"} | Missing/blank creation name or invalid supplied update name. |
{"error":"parameter too long: name. max length 80 characters"} | Name exceeds 80 characters. |
{"error":"stock category parent does not exist"} | Positive parent is missing or deleted. |
{"error":"stock category parent would create a cycle"} | Changed parent would create or enter a cyclic ancestor chain. |
{"error":"stock item does not exist"} | Normalized membership contains a missing/deleted stock ID. |
{"error":"inventory write failed"} | Checked tenant persistence failed and rolled back. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Changes only supplied name, parentID and stock; one positive scalar id is required. Arrays/bulk IDs are rejected.
- Validates nonempty trimmed name, 80-character length and every normalized stock member. A changed parent is checked for active existence and cycles. Existing unchanged legacy parent pointers are preserved.
- No changed mapped values (including unrecognized-only input) returns {warning:"No Change."} without stock refresh or events. Changed fields stamp the server datetime and write checked field history.
- Tenant row changes, membership repairs and required audit writes are checked within one transaction; a failure rolls them back and returns an error. Configured events run only after commit.
- Only non-deleted categories are read or changed. No quantity, price or accounting-provider availability check is applied.
- The source search found no direct caller in the mobile JavaScript app or its
m/wwwintermediary for this endpoint. - Post-commit event failures on event-producing writes return the committed success plus warning:
saved, but a configured event failed; do not repeat creation. Review the saved record before retrying.
Side effects
- Updates category values and timestamp; invalidates stockcategorys cache. Records checked mapped-field history.
- Rebuilds affected active stock items’ category_ids as JSON text containing string IDs and categories as comma-separated names. Advances stock last_edited and sets edited_uuid to the endpoint name; invalidates stocks cache. No stock quantity movement occurs.
- Fires configured StockCat_edit after a committed changed mapped save or any successful legacy save. No event fires for a mapped No Change warning.
See it in Fieldmotion
CRM1
No direct CRM1 caller was found for this endpoint. The legacy Stock Categories screen uses StockCategory_get and StockCategories_listByParent.
CRM2
Stock Categories → Save uses generic updateData(table:stockCategory) with id/name/stock; filter StockCategory_updateData. Other generic editors can send parentID.
Related endpoints
StockCategories_listretrieves a flat category projection.StockCategory_getRequestedDetailsuses the mapped CRM2 field names.