Find stock records by item code

When to use this endpoint

Use when an external catalog/document supplies stock codes instead of local IDs. Codes are not required to be unique, so multiple stock rows can match one code.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. The handler calls the user-login guard but adds no stock-page, finance or administrator permission check.

Queries use the authenticated tenant. Sign numeric values as strings; JSON-encode only parameters described as JSON text. See Getting started.

Parameters

Parameter	Type	Required	Description
`code`	String	Either code or codes	A truthy trimmed single code takes precedence over codes. The single code is trimmed before matching. The literal string "0" fails this guard and falls through to codes.
`codes`	JSON array text	Either code or codes	JSON-decodes a truthy trimmed string. Native arrays are not accepted here because trim runs on this parameter. Only string members whose trimmed value is truthy survive; blank/whitespace and string "0" are discarded. Accepted member whitespace is checked but not removed before matching.
`fields`	Native array or JSON array text	No	Default id,code. 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. Unknown/duplicate names ignored; no surviving fields is an error. ID is not automatically added.

Example request

$items = FM_api('Stocks_getByCode', ['codes'=>json_encode(['FLT-01','FLT-02']), 'fields'=>json_encode(['id','code','name'])]);

Example response

[{"id":"1042","code":"FLT-01","name":"Filter cartridge"}]

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: code or codes"}`	Neither code nor codes is truthy after trimming; single code "0" without a usable codes value also fails.
`{"error":"no codes in list"}`	Decoded list has no accepted string members; [] and a list containing only "0" reach this error.
`{"error":"invalid parameter: fields"}`	Supplied fields does not decode to an array.
`{"error":"no fields selected"}`	No allowlisted requested fields survive.
`[]`	No non-deleted stock matches the codes.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

Code parsing precedes login; a usable request then calls Core_requireLogin. Malformed JSON codes is not separately validated as an array and has no reliable input-error contract; use valid JSON text.
Filters deleted=0 but includes archived stock. Matching follows database collation; duplicate input codes do not duplicate result rows and duplicate stored codes can yield multiple records.
No order, input-order preservation, pagination, quantity check, supplier/department filter or stock feature gate.
Returns object rows and raw stored scalar types, not a map keyed by code. JSON columns remain encoded. A projection may omit id and code entirely.
No direct mobile caller was found in the current app JavaScript or m/www intermediary. The app receives stock through syncDownloads, which selects non-deleted stock by edit timestamp; these calls are not the app synchronization protocol.

Side effects

Read-only; no stock edit, movement, event or cache invalidation.

See it in Fieldmotion

CRM1

No direct caller for Stocks_getByCode was found. CRM1 stock document pickers use Stock_listByCategory or Stock_listByIds instead.

CRM2

No direct caller was found. CRM2 Stock.getInstance resolves known IDs through Stocks_getById; the Stocks module uses mapped queries.

Related endpoints

Stock_listByIds resolves already-known IDs.
Stock_listByCategory provides a category-filtered active picker.