Stock items and catalogue maintenance
Adjust warehouse stock quantity
/a/Stock_setInStock
Add a signed nonzero quantity to the catalogue’s in_stock value.
When to use this endpoint
Use only when intentionally changing warehouse balance. instock is a delta: 3 adds three and -3 subtracts three.
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 | Integer-compatible | Yes | Positive stock catalogue ID. It is not a stock-container row ID, category ID or supplier ID. |
instock | Float-compatible | Yes | Signed increment; float-converted zero, omission or blank is rejected. Fractional and negative increments are accepted. |
Example request
$result = FM_api('Stock_setInStock', ['id'=>'18', 'instock'=>'-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: id"} | ID is absent or integer-converts below 1. |
{"error":"missing or invalid parameter: instock"} | The increment float-converts to zero. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- instock is a signed, finite, nonzero warehouse increment; fractional/negative deltas and negative resulting balances remain supported for legacy callers. It is not an absolute balance.
- Locks an undeleted target, writes in_stock plus last_edited/edited_uuid=Stock_setInStock, and records history. Missing targets and failed writes return an error.
- Does not adjust container balances or create a balanced logistics movement. No threshold email branch is added here.
- 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 warehouse stock/history/cache changes, then configured Stock_edit.
See it in Fieldmotion
CRM1
CRM1 invoice stock-row editing uses Stock_setInStock with positive/negative deltas when old/new row quantities change. Filter for instock rather than an absolute balance.
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 stock logistics use Stock_transaction; no direct caller of this legacy increment was found.
Related endpoints
Stock_updateStockLevels— Add a signed quantity to a legacy stock/container balance without balancing warehouse stock.Stock_get— Read the full saved stock row, with selected manufacturing metadata flattened for the legacy editor.