Goods returns
Set legacy return delivery amounts
/a/GoodsReturnedNote_setDeliveryCosts
Replace the return header’s delivery net amount, tax code and absolute tax amount.
When to use this endpoint
CRM1 saves these fields from the return-note delivery controls. Calculate the tax amount before sending it; the API does not look up the code’s rate or derive gross/net totals.
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 | Integer-converted value | Yes | Positive whole header ID; target must exist. |
delivery_net | Number or numeric string | Yes | trim then floatval, with blank becoming 0. Negative values are accepted; written to a decimal column. |
delivery_taxcode | String | Yes | Stored code, including empty string. No category existence or rate validation. |
delivery_tax | Number or numeric string | Yes | Absolute tax amount, not a rate/percentage; blank becomes 0, negative values accepted. |
Example request
FM_api('GoodsReturnedNote_setDeliveryCosts', ['id'=>642,'delivery_net'=>'12.50','delivery_taxcode'=>'20','delivery_tax'=>'2.50']);Example response
{"ok":1}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":"no return note ID provided"} | id absent. |
{"error":"missing or invalid parameter: delivery_net"} | delivery_net absent; presence checks occur before tenant login guard. |
{"error":"missing or invalid parameter: delivery_taxcode"} | delivery_taxcode absent; presence checks occur before tenant login guard. |
{"error":"missing or invalid parameter: delivery_tax"} | delivery_tax absent; presence checks occur before tenant login guard. |
{"error":"goods return write failed"} | A primary write or history insert failed; the transaction is rolled back. |
{"error":"goods return read failed"} | A required locking read failed; no changes commit. |
{"error":"goods return transaction failed"} | Starting/committing the tenant transaction failed. |
{"error":"goods return operation failed"} | Unexpected database/JSON processing failure; no changes commit. |
{"error":"goods return record does not exist"} | Header missing; no patch commits. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- All three delivery values are required. Blank numeric values normalize to zero; other values must be finite. Tax is an absolute amount; negative delivery amounts remain accepted.
- Positive whole existing header ID required. Failed writes/history or missing targets commit no patch.
- Changed values advance last_edited. Unchanged inputs return ok without writing. No total_net recalculation, line edit or stock movement.
Side effects
- Invalidates goods_returned cache and commits checked field history with changed values. No tax-rate calculation, stock movement, export, notification or PDF generation.
See it in Fieldmotion
CRM1
pageGoodsReturnedNote saves delivery inputs here and calculates gross from net + tax in the browser.
CRM2
CRM2’s mapped header aliases are deliveryNet, deliveryTaxCode and the exact deliverTax; layout saves use GoodReturned_updateData.