Stock items and catalogue maintenance
Read stock IDs in a batch
/a/Stocks_getById
Read an explicit stock-ID selection using saved snake_case columns.
When to use this endpoint
Pass ids as a native list or encoded JSON; fields uses storage names rather than mapped camelCase names.
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 |
|---|---|---|---|
ids | Native/JSON ID list | Yes | Native or decoded JSON ID lists are validated, then integer-converted and deduplicated, including zero/negative values. Empty lists return no ids in list; malformed JSON, scalars and unsupported list elements return controlled parameter errors. |
fields | Native/JSON field list | No | Allowlist: amt_trigger,average_cost,categories,category_ids,cdate,code,description,edited_uuid,id,in_stock,is_archived,last_edited,meta,name,nominal_code,notes,owner_id,price,supplier_id,tax_rate,price_bands. Defaults to all allowed columns. Invalid fields are discarded; an explicit projection with no valid names is rejected. id is not auto-added. |
Example request
$result = FM_api('Stocks_getById', ['ids'=>json_encode(['18','21']), 'fields'=>json_encode(['id','name','price'])]);
Example response
[
{
"id": "18",
"name": "Valve",
"price": "20.0000"
}
]
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: ids"} | ids absent/null. |
{"error":"no ids in list"} | The decoded list is empty. |
{"error":"no fields selected"} | Explicit projection contains no allowed columns. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Bare row array; deleted rows excluded, archived rows included. Missing IDs are omitted. No order, pagination or input-order reconstruction is applied.
- Selected storage values retain driver types. category_ids/meta/price_bands are encoded JSON strings; no supplier expansion, category repair or computed allocation fields are added.
- Unlike Stocks_list, supplying fields=[name] returns name only and does not force id; this distinction matters to client row mapping.
- ids and fields must be native or decoded JSON lists with supported scalar elements. Malformed structures now return controlled parameter errors. An empty ID list retains no ids in list; empty/unknown-only fields retains no fields selected. Selected storage columns and scalar types are unchanged.
Side effects
- Read only.
See it in Fieldmotion
CRM1
CRM1 Job bill-of-materials, quote stock pickers and requisition rows fetch selected IDs with Stocks_getById and encoded lists.
CRM2
CRM2 stock model/header cache, exports and Job bill-of-materials use Stocks_getById. Keep the requested id field when the consumer maps results back to objects.
Related endpoints
Stocks_list— Stream a bare JSON stock list with warehouse quantities and an optional field projection.Stock_getRequestedDetails— Return projected stock rows with optional supplier and allocation summaries.Stock_get— Read the full saved stock row, with selected manufacturing metadata flattened for the legacy editor.