Stock items and catalogue maintenance
List stock catalogue rows
/a/Stocks_list
Stream a bare JSON stock list with warehouse quantities and an optional field projection.
When to use this endpoint
Use for picker lists/incremental catalogue reads. Stock_list calls Stocks_list with the same request and output contract.
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 |
|---|---|---|---|
fields | Native/JSON list | No | Allowlist: id,name,code,in_stock,average_cost,price,nominal_code,tax_rate,description,notes,price_bands,is_archived. id is always selected. Omission, malformed input or no usable fields returns the default eight fields. |
all | String/integer-compatible | No | Value comparing equal to 1 includes archived items; otherwise requires is_archived=0. Deleted rows are always excluded. |
last_edited | SQL datetime string | No | When present, strict last_edited > supplied value AND < server now. Empty input still adds a comparison. This is not a deletion feed. |
supplier_id | Integer-compatible | No | Positive scalar default supplier_id match; does not join stock_suppliers. |
cat_id | Integer-compatible | No | Nonzero category ID matched inside category_ids using JSON_SEARCH; no category-active join. |
Example request
$result = FM_api('Stocks_list', ['fields'=>json_encode(['id','name','code']), 'all'=>'1']);
Example response
[
{
"id": 18,
"name": "Valve",
"code": "VALVE-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. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Default fields: id,name,code,in_stock,average_cost,price,nominal_code,tax_rate. id is always present; requesting only invalid names or id falls back to that default projection. Unknown names are silently ignored.
- The endpoint streams JSON directly and marks output done; there is no ok/data/total wrapper. id/is_archived convert to integers and in_stock/average_cost/price/tax_rate to floats when selected. JSON price_bands remains encoded.
- No ORDER BY, pagination, offset or row limit is implemented. last_edited bounds are strict and server-now is recalculated per request; account timezone/SQL datetimes matter when polling.
Side effects
- Read only; no timestamp/cursor persistence.
See it in Fieldmotion
CRM1
CRM1 Stock code checks, quote/invoice/SOR pickers and supplier editors call Stocks_list, often with JSON-encoded fields. Filter Network for Stocks_list; Stock_list is its callable singular alias.
CRM2
CRM2 pickers and QuickBooks setup checks use Stocks_list, while the main catalogue uses Stocks_getDataTable. No direct singular Stock_list caller was found.
Related endpoints
Stocks_getById— Read an explicit stock-ID selection using saved snake_case columns.Stocks_getDataTable— Return named stock rows with mapped filters, paging and optional supplier/allocation summaries.Stock_get— Read the full saved stock row, with selected manufacturing metadata flattened for the legacy editor.