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

ParameterTypeRequiredDescription
fieldsNative/JSON listNoAllowlist: 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.
allString/integer-compatibleNoValue comparing equal to 1 includes archived items; otherwise requires is_archived=0. Deleted rows are always excluded.
last_editedSQL datetime stringNoWhen present, strict last_edited > supplied value AND < server now. Empty input still adds a comparison. This is not a deletion feed.
supplier_idInteger-compatibleNoPositive scalar default supplier_id match; does not join stock_suppliers.
cat_idInteger-compatibleNoNonzero category ID matched inside category_ids using JSON_SEARCH; no category-active join.

Example request

$result = FM_api('Stock_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

ResponseCondition
{"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.