Stock items and catalogue maintenance
Edit one mapped stock field
/a/Stock_updateField
Set one mapped field for one or more stock items using the inline-save contract.
When to use this endpoint
Use field/val with mapped names. Full category, tax picker and price-band widget workflows belong on Stock_updateData.
Authentication and permissions
Authenticate with a signed API key or a logged-in CRM session on the account’s routed host. API keys act as their owner; session calls require dispatcher CSRF protection where configured. IDs address the authenticated tenant.
These stock handlers do not add a Stock page-action or CRM2 role check, and the dispatcher has no Stock/Stocks TeamAccess object mapping. CRM2 screen controls are separate from this shared API contract; their roles must not be assumed to apply to CRM1.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id / ids | Scalar or native ID list | Yes | id takes precedence. Lists are native arrays; encoded JSON text is not decoded. |
field | Mapped field name | Yes | Writable mapped names: name,averageCost (alias cost),inStock,categories,categoryIDS,code,isArchived,amtTrigger,description,supplierID,price,notes,nominalCode,taxRate,meta,priceBands. Primary id and lifecycle/display fields cDate,ownerID,lastEdited,editedUUID are rejected. Metadata projections: metaManufacturer,metaBarcode,metaManufacturerPartNo,metaSupplierPartNo,metaSuppliers,metaUnit,metaTaxRateID,metaNominalCodeID,metaNominalID,metaNominalName,customValues,metaReferrenceType. taxType is a composite picker with id,taxRate,nominalID,nominalName,nominalCode. Preserve the misspelling metaReferrenceType. |
val | Non-null mapped value | Yes | Empty strings/zero follow generic type conversion. Use native objects/arrays for JSON values as sent by the UI; null is treated as absent. |
Example request
$result = FM_api('Stock_updateField', ['id'=>'18', 'field'=>'isArchived', 'val'=>'1']);
Example response
{
"ok": 1,
"oldData": [
{
"id": "18",
"is_archived": "0"
}
]
}
Application errors can use HTTP 200. Inspect error/warning fields; database numeric values can be strings unless this handler explicitly converts them.
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: field"} | field absent/null. |
{"error":"missing or invalid parameter: val"} | val absent/null. |
{"error":"missing or invalid field"} | Field not in the stock map. |
{"error":"missing or invalid parameter: id/ids"} | No selection supplied. |
{"error":"Unable to update record"} | A mapped write fails. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Mapped field/val and id/ids remain the inline contract; returned oldData contains the target’s prior storage column and ID. Missing/invalid target selections return errors.
- Primary ID and lifecycle/display fields are rejected. Supported business fields use the full-save transaction and category/picker hooks rather than bypassing synchronization.
- field=taxRate retains its inline numeric percentage meaning, distinct from a full-save category-ID selection. field=metaTaxRateID selects a tax category; categoryIDS synchronizes membership; taxType supports the native picker object.
- Primary changes and stock history use a checked transaction. Failed validation/read/write/commit returns an error and rolls back open changes. Configured events/notices run after commit; a post-commit warning means the save succeeded and must not be repeated blindly.
Side effects
- Full stock/category/history/cache handling as needed, then Stock_edit/mention follow-ups.
See it in Fieldmotion
CRM1
No direct CRM1 Stock_updateField caller was found. Its inline editor uses snake_case Stock_updateOneField.
CRM2
Generic layout autosave derives Stock_updateField; observed moduleStocks inline actions also use Stock_updateData. Both routes now retain required business hooks; inspect the actual Network payload.
Related endpoints
Stock_updateData— Update stock fields, category membership and picker values through the full mapped save.Stock_updateOneField— Set name, code, archive flag or threshold through the legacy inline editor.Stock_getRequestedDetails— Return projected stock rows with optional supplier and allocation summaries.