Writing to an ERP
Reads are recoverable. Writes here post to a ledger the customer closes their books against, so the three traps below are worth knowing before the first PUT, not after.
The missing key creates a duplicate
acumatica_put_record is one call for both create and update, and Acumatica decides which from the payload: **include the key fields and it updates that record; omit them and it creates a new one.**
There is no error in between. Intend to update sales order SO / 000123, forget OrderNbr, and you have made a second order — which then flows downstream into allocation, picking, and the customer's demand figures. Nothing fails, so nothing tells you.
Send the keys. Always. acumatica_describe_entity lists them.
Detail lines are replaced as given
Send a Details collection and it becomes the record's lines. Send two lines to an order that has five and you have deleted three.
To change one line, read the record with expand: "Details" first, modify the collection you got back, and send the whole thing. This is also why the value wrapper is handled for you — a hand-built payload is where the omissions creep in.
Actions are the UI button, including everything behind it
acumatica_invoke_action runs the same business logic as clicking Release in the interface: GL entries posted, inventory allocated, documents generated, emails possibly sent. Most of it is not reversible through the API — the correction is another document (a credit memo, a reversing entry), not an undo.
Long-running actions answer 202 with a URL to poll. The tool reports it rather than blocking, because "still running" is a truthful answer and holding a licensed concurrency slot for several minutes is not. Poll it with acumatica_request: 204 means finished, 202 means keep waiting.
A failed delete is usually telling you something
Acumatica refuses to delete anything released or referenced downstream. When acumatica_delete_record fails on a real document, that is generally correct — the ERP is protecting an audit trail. The operation you actually wanted is an action: void, cancel, or reverse. Deleting is for a draft nobody has acted on.
Two habits worth keeping
Connect a read-only user first. Create an Acumatica user with a read-only role for the exploration phase and swap it only when writing is the agreed scope. Permissions in the ERP are a harder boundary than intent in a prompt.
Read the record back. Every write returns the saved record; check that what came back is what you meant, particularly on the first write against an entity whose customizations you have not seen.