Stock items and catalogue maintenance
Adjust one stock allocation balance
/a/Stock_updateStockLevels
Add a signed quantity to a legacy stock/container balance without balancing warehouse stock.
When to use this endpoint
CRM1 Job-table edits use this to return/subtract quantities for a user allocation. Prefer the logistics transaction API for a full movement.
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.
The handler checks that the tenant database context is defined rather than calling Core_requireLogin. Use normal authenticated dispatcher access; this is not a public or cross-tenant endpoint. No extra Stock page-action/CRM2 role check is added here.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
stock_id | Integer-compatible | Yes | Positive catalogue stock ID. |
container_id | String UUID or integer-compatible | Yes | Vehicle UUID string for type 2; positive numeric user/location/other container reference otherwise. Not an allocation row ID. |
container_type | Integer-compatible | Yes | Any positive integer passes validation; only 1/2/3 additionally touch the owning user/vehicle/location timestamp. |
amt | Float-compatible | Yes | Signed nonzero increment; negative and fractional values are accepted. |
Example request
$result = FM_api('Stock_updateStockLevels', ['stock_id'=>'18', 'container_id'=>'37', 'container_type'=>'1', 'amt'=>'-1.5']);
Example response
{
"ok": 1
}
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: stock_id"} | Missing/nonpositive ID/type or zero quantity. |
{"error":"missing or invalid parameter: container_id"} | Missing/nonpositive ID/type or zero quantity. |
{"error":"missing or invalid parameter: container_type"} | Missing/nonpositive ID/type or zero quantity. |
{"error":"missing or invalid parameter: amt"} | Missing/nonpositive ID/type or zero quantity. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- amt is a finite signed nonzero allocation increment, with fractions and negative balances preserved. It does not change warehouse in_stock or reinterpret this call as a balanced stock movement.
- container_type=2 preserves a string vehicle UUID; other types require a positive numeric container reference. Only user/vehicle/location types touch an owner sync timestamp.
- Locks an undeleted stock item and its allocation. Existing allocation rows update in place, preserving row ID, inventory_id, metadata and threshold. New balances insert a row; ambiguous duplicate existing rows return an error instead of destroying metadata.
- Allocation balance, owner timestamp and stock audit commit together. An owner/update/audit failure rolls back the adjustment.
- 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
- Checked allocation/history/owner timestamp/cache writes; no permanent deletion/reinsertion of an existing allocation.
See it in Fieldmotion
CRM1
In CRM1 Job tables, changing a selected stock cell calls Stock_updateStockLevels for the old/new item using the Job user as container_type=1. A missing/non-user source can produce container_id=0, which this handler rejects.
CRM2
Open Stocks in CRM2. Stock layouts derive Stock_createData, Stock_updateData and Stock_getLayoutDetails through the shared helpers; the grid calls Stocks_getDataTable. Inspect the exact function name in Network requests. Modern allocation/write-off screens use Stock_transaction rather than this legacy balance adjustment.
Related endpoints
Stock_find— Read the stock-container rows associated with one catalogue item.Stock_setInStock— Add a signed nonzero quantity to the catalogue’s in_stock value.