Goods returns
Read mapped return-note headers
/a/GoodReturned_getLayoutDetails
Read selected return-header fields as a list, not a joined layout document.
When to use this endpoint
Use to load mapped header fields for a known return ID or a filtered collection. Despite the name, this handler only invokes the basic mapped reader; it does not expand nested layout widgets or return lines.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Session CSRF and account/IP restrictions still apply. These handlers add no goods-return, finance, department, owner or page-role permission check.
Records belong to the authenticated tenant. CRM1 shows this workflow when the employer features bit 262144 is enabled; CRM2 uses features2.goodsReturnedNotes. These are UI gates, not checks performed by these handlers.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id / ids | Integer or native array | No | Restrict return IDs; id wins over ids. Each ID is integer-converted. An omitted selector or empty ID array does not restrict the lookup. |
fields | Native array of strings | No | Mapped field aliases to return; omitted means every mapped field. Unknown fields are ignored and id is always included. Do not pass a JSON-encoded string. |
Mapped field filters | Scalar or native array | No | Other mapped aliases are ANDed: text/date/JSON scalar values use lowercased, trimmed equality, arrays use membership. Numeric filters use integer conversion, including mapped decimal/float values. Non-numeric numeric-array members are discarded; an empty usable numeric list matches nothing. |
order | Alias or native array | No | One alias, a list of aliases, or entries {id:"cDate",dir:"desc"}. Unknown aliases are ignored; only exact desc gives descending order. No default ordering. |
advanceSearch | Native array | No | Native structured conditions: exact mapped id/column, allowlisted condition, scalar/scalar-list value, optional AND/OR andOr and ( or ) special. Raw where is rejected. |
Header aliases | Field names | For fields/filters | id, cDate, lastEdited, supplierID, grnID, notes, totalNet, deliveryNet, deliveryTaxCode, deliverTax and customValues. deliverTax is the exact tax alias. |
Example request
FM_api('GoodReturned_getLayoutDetails', ['id'=>642, 'fields'=>['grnID','supplierID','notes','cDate','customValues']]);Example response
[{"grnID":"531","supplierID":"84","notes":"Damaged packaging","cDate":"2026-10-07 10:30:00","customValues":"{}","id":"642"}]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":"unsupported raw advanced search"} | A rule contains where instead of an allowlisted mapped structured condition. |
{"error":"missing or invalid parameter: orderDesc"} | Direction is not asc/desc. |
{"error":"missing or invalid parameter: fields"} | fields must be a native string array. |
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 an array even for one ID; no match is
[]. A failed database read is also collapsed to[]rather than a distinct database error. - No offset, length, limit or DataTables counters are implemented by this reader. An unfiltered call can return the entire tenant table.
- Stored database scalar types are preserved, commonly numeric strings and SQL NULL as JSON null. JSON columns remain JSON-encoded strings; there is no automatic decoded custom object.
- There is no supplier name enrichment, deleted/archived related-record filtering or line/stock reconciliation.
- Native filter shapes and structured advanced-search/order controls are validated before the helper executes. Raw SQL is not supported.
Side effects
- Reads only; does not save layout, calculate totals or change stock.
See it in Fieldmotion
CRM1
CRM1’s goods-return pages use the legacy GoodsReturned/GoodsReturnedNote calls instead of this mapped operation.
CRM2
CRM2’s goods-return layouts use the goodReturned mapping in php/Layout/_map.php: create/read/update are GoodReturned_createData, GoodReturned_getLayoutDetails and GoodReturned_updateData. The table uses GoodsReturned_getDataTable; its delete action calls GoodReturned_delete.