Receive goods through the legacy workflow

When to use this endpoint

Use the CRM1 Goods Received creation flow. Obtain purchase-order line IDs and stock types from PurchaseOrderEntries_get, then submit the quantities actually delivered. This legacy path does not create the inventory batches/serial movement records used by the CRM2 widget path.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Session CSRF, account-active and IP restrictions still apply. These handlers add no receipt-specific page, finance, department or record-owner permission check.

Records are scoped to the authenticated tenant. CRM1 displays Goods Received with employer feature bit 262144; CRM2 checks features2.goodsReceivedNotes. Those screen gates are not enforced by these handlers. Mobile receipt routes run separately through the mobile intermediary and have different permission and ownership checks.

Parameters

Parameter	Type	Required	Description
`supplier_id`	Integer	Yes	intval must be positive; the supplier need not exist or be active.
`po_id`	Integer	No	Defaults to 0; nonpositive values are unlinked. A positive ID must identify an active PO. Approval and supplier/PO consistency are not checked.
`date_received`	Date/time string	No	Falsey/omitted defaults to server now. Accepts YYYY-MM-DD (normalized to midnight) or YYYY-MM-DD HH:MM:SS, without timezone conversion; invalid dates are rejected.
`notes, supp_invoice, supp_dnn`	String	No	Defaults to empty text; supplier invoice/delivery-note references are not unique-checked.
`rows`	Native array or JSON array text	No	Native list or JSON array text of [poe_id,type,item,quantity,description]. Type 1 uses item as an active catalog ID; type 2 uses description at index 4, falling back to item when absent. Omitted/blank means no lines; malformed rows/JSON reject the entire save. Quantities are non-negative decimals with at most four places; zero skips.
`po_status`	Integer	No	Defaults to 0 and must be one of 0 Open, 1 Part Received, 2 Received, 3 Over-received, 4 Cancelled. Caller-supplied, not calculated from quantities; omitting can reset a linked PO to Open.

Example request

FM_api('GoodsReceived_newNote', [
	'supplier_id'=>'84', 'po_id'=>'482', 'date_received'=>'2026-10-09',
	'supp_invoice'=>'INV-1042', 'supp_dnn'=>'DEL-1042', 'notes'=>'Checked',
	'rows'=>[['901','1','318','2','Filter'],['902','2','0','1','Packing charge']],
	'po_status'=>'1',
]);

Example response

{"ok":1,"id":"531"}

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: supplier_id"}`	Supplier integer-coerces below 1.
`{"error":"purchase order does not exist"}`	Positive po_id does not identify an active PO; no writes commit.
`{"error":"stock does not exist"}`	A catalog row references missing/deleted stock; no writes commit.
`{"error":"goods receipt write failed"}`	Checked persistence fails; the transaction rolls back.

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

Behaviour and edge cases

Requires tenant upgrade 798 to preserve fractional receipt amounts. Header, lines, catalog increments, PO status and their history writes commit in one checked transaction; a failed read/write/history/commit rolls the operation back.
Catalog rows require active stock records and add the decimal quantity to stock.in_stock. Repeated rows for one catalog item are aggregated for its stock update. Free-text rows do not move catalog stock. Dates and text are parameterized.
A positive linked PO is locked and checked active before stock. A changed caller-supplied status updates the PO edit timestamp and status history. There is no approval, supplier-match or ordered/outstanding-quantity cap.
created_by is the authenticated user. Header-only receipts remain allowed at the API. No inventory batches, container allocation, dispatch or form synchronization are performed; use the mapped receiving widget for that workflow.

Side effects

Transactional receipt header/line/history writes, catalog increments and stock history/edit timestamps/edited_uuid, optional linked PO status/history/edit timestamp; affected caches are invalidated. No inventory/container movements.

See it in Fieldmotion

CRM1

Open Goods Received → Create, choose supplier/PO and enter received quantities. Inspect GoodsReceived_newNote; the UI sends five-slot rows and its selected po_status.

CRM2

CRM2 uses GoodReceived_createData via its goodReceived layout and entry widget, not this legacy receiver. The mobile app uses separate GoodsReceived_save through m/www; its whole-quantity/ownership guards do not apply to this CRM endpoint.

Related endpoints

GoodReceived_createData — CRM2 inventory-aware intake.
GoodsReceivedEntries_get — read the saved tuples.
GoodsReceived_getDT — show the legacy list.