When to use this endpoint

Use for layout initialization, not for the tax-rate percentage contract of Stock_getRequestedDetails.

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
id / idsScalar ID or native ID arrayNoid takes precedence over ids. Without either, reads can return all matching undeleted stock. Explicit empty ID arrays return [] in Stock_getRequestedDetails; Stock_getLayoutDetails retains its legacy broad selection for an empty array; JSON-encoded ID lists are not decoded here.
fieldsNative array of field namesYes for this wrapperUse mapped names, not snake_case columns. Mapped names: id,name,averageCost (alias cost),cDate,ownerID,inStock,categories,categoryIDS,lastEdited,code,isArchived,amtTrigger,description,supplierID,price,notes,nominalCode,taxRate,meta,editedUUID,priceBands. Metadata projections: metaManufacturer,metaBarcode,metaManufacturerPartNo,metaSupplierPartNo,metaSuppliers,metaUnit,metaTaxRateID,metaNominalCodeID,metaNominalID,metaNominalName,customValues,metaReferrenceType. taxType is a composite picker with id,taxRate,nominalID,nominalName,nominalCode. Preserve the misspelling metaReferrenceType.
orderNative arrayNoMapped field names or {id:field,dir:asc|desc} objects; no order is added unless supplied.
Mapped filtersScalars/native arraysNoKnown map keys filter by exact normalized value/list. Numeric filters integer-convert. No implicit archive restriction. Typed advanceSearch is a native list of {id:stock_name,condition:equal,value:Valve} rules. Supported conditions: equal,contains,notEqual,greaterThan,greaterThanOrEqual,lesserThan,lesserThanOrEqual. A rule containing raw where SQL is rejected.

Example request

$result = FM_api('Stock_getLayoutDetails', ['id'=>'18', 'fields'=>['id','name','taxRate','widgetPriceBand']]);

Example response

[
  {
    "id": "18",
    "name": "Valve",
    "taxRate": "7",
    "widgetPriceBand": "{}"
  }
]

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.
{"error":"invalid advanced search"}Raw SQL filters are rejected by the mapped helper.

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

Behaviour and edge cases

  • Returns a mapped row list; fields must be a nonempty native string list. widgetPriceBand adapts the stored priceBands JSON and temporary supporting fields are removed.
  • taxRate in this response is a category ID. A saved positive ID is reused only when it exists and its rate matches the item. Blank/stale/mismatched IDs fall back to the first category ordered by ID with the saved rate. Explicit saved no-tax 0 remains 0.
  • This deterministic fallback is read-only; it does not rewrite the saved tax metadata.

Side effects

  • Read-only layout projection and category lookup.

See it in Fieldmotion

CRM1

No direct current CRM1 layout-reader caller was found; its stock editor uses legacy Stock_get/getDetails.

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. Open a stock layout: getLayoutDetails derives this route and requests the layout field array.

Related endpoints

  • Stock_updateData — Update stock fields, category membership and picker values through the full mapped save.
  • Stock_createData — Create a catalogue record from CRM2 layout fields and synchronize category membership.
  • Stock_getRequestedDetails — Return projected stock rows with optional supplier and allocation summaries.