Read the legacy goods-return table

When to use this endpoint

Use for CRM1’s Goods Returned table. Its row IDs open pageGoodsReturnedNote; do not substitute the differently shaped mapped GoodsReturned_getDataTable response.

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
`length`	Integer	Yes	Positive whole page size. Zero, negatives and fractions are rejected; no -1 all-rows mode.
`start`	Integer	No	Whole non-negative SQL offset, default 0.
`draw`	Integer	No	Echoed DataTables draw, default 0.
`order`	Native array	No	Only the first native order entry: zero-based column 0 ID, 1 supplier, 2 received date, 3 return date, 4 received-note ID, 5 return notes. Exact desc selects descending. Unknown columns fall back to return ID; equal sorts use an ID tiebreaker.
`search`	Native object	No	Native object with scalar value: trimmed/lowercased substring search on supplier name, return ID, received-note ID and notes. "0" is searched rather than ignored.
`dateFrom / dateTo`	Date strings	No	Validated absolute YYYY-MM-DD, independently optional. Filter return-header cdate inclusively from 00:00:00/to 23:59:59. Reversed bounds are rejected. Not mapped relative day offsets.

Example request

FM_api('GoodsReturned_getDT', ['length'=>25, 'start'=>0, 'draw'=>1, 'order'=>[['column'=>0,'dir'=>'desc']]]);

Example response

{"draw":1,"recordsTotal":"1","recordsFiltered":"1","data":[["642","Example supplier","2026-10-01 09:00:00","2026-10-07 10:30:00","531","Damaged packaging","420",""]]}

Tuple positions are return ID, supplier name, received date, return date, received-note ID, return notes, purchase-order ID and an empty action cell. Numeric database values/counts commonly remain strings. Left-joined missing values are null.

Return date is the header’s own cdate, not the linked received date; issue #5007 tests this distinction. recordsTotal counts all return headers; recordsFiltered applies search/date filters.

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: length"}`	Missing/non-positive/non-whole page size.
`{"error":"missing or invalid parameter: dateFrom"}`	Invalid/impossible date; analogous guards apply to dateTo/start/search/order.
`{"error":"invalid date range"}`	dateFrom later than dateTo.
`{"error":"goods return read failed"}`	Rows or either count query failed, not an empty successful table.

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

Behaviour and edge cases

Only first order entry is used; unknown columns safely fall back to return ID. ID tiebreaking stabilizes equal sort values.
Independent absolute date bounds qualify grt.cdate, not the received date. Query/count failures return an error.
No related deletion/archive filter, line/stock aggregation or search over item descriptions/received notes/PO numbers.
Offset/length paging; no export/all flag.

Side effects

Read only. No total recalculation or stock movement.

See it in Fieldmotion

CRM1

pageGoodsReturned configures widgetTable with GoodsReturned_getDT, opens the returned ID with pageGoodsReturnedNote and exposes GoodsReturnedNote_delete as the delete action.

CRM2

CRM2’s corresponding table uses the mapped GoodsReturned_getDataTable, not this positional API.