Reverse a posted entry and post what it should have said, in one transaction
const url = 'https://example.com/v1/entities/example/entries/example/correct';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"reason":"example","replacement":{"legs":[{"account":"example","commodity":"example","amount":"-12.00","memo":"example","tax_code":"example"}],"dt":"example","narration":"example","origin":"example","code":"","comment":"","tags":[["example"]]},"dt":"example","narration":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/entities/example/entries/example/correct \ --header 'Content-Type: application/json' \ --data '{ "reason": "example", "replacement": { "legs": [ { "account": "example", "commodity": "example", "amount": "-12.00", "memo": "example", "tax_code": "example" } ], "dt": "example", "narration": "example", "origin": "example", "code": "", "comment": "", "tags": [ [ "example" ] ] }, "dt": "example", "narration": "example" }'Reverse a posted entry and post what it should have said, linked to the original (issue 0006).
reverse withdraws a booking; this restates it, which is the ordinary case. An entry on the wrong
account, for the wrong amount or on the wrong date usually needs replacing, not just withdrawing.
Both halves land in one transaction, so there is no moment at which the original is reversed and nothing stands in its place, and a concurrent report cannot see the books with the entry missing. The replacement is an ordinary entry (account paths and exact decimal amounts) and goes through the same balance, account, precision and period-lock rules as any other posting. A correction that would land in a closed month is refused; reopen the month to fix it.
For a statement line, POST /lines/{id}/reexplain does this and the re-explanation together, so the line
is never momentarily unexplained.
Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The entity this path is relative to
The entity this path is relative to
Request Bodyrequired
Section titled “Request Bodyrequired”Reverse a posted entry and post what it should have said, in one transaction.
A reversal says only “this was wrong”. A correction says what was meant, which is the ordinary case: an entry booked to the wrong account, for the wrong amount or on the wrong date is restated, not just withdrawn. Doing both in one command means the books never pass through a state, visible to a concurrent report, where the original is reversed and nothing stands in its place.
Nothing is edited. The original stays posted and in the sums, an exact mirror is posted beside it, and the
replacement is posted as its own entry. All three carry the actor that wrote them, and one
entry.corrected audit action records why.
object
Why the original was wrong; recorded verbatim
What the corrected entry should have said: the same shape as writing one, minus the reason.
There is one reason for the whole correction, and it belongs to the correction, not the replacement. A separate reason on the replacement would invite two different sentences about one act.
object
Every leg of the replacement; nets to zero per commodity
One leg of a manual journal entry: an account, a currency and a signed amount.
Unlike a line booking’s legs, these are the whole entry. No cash leg is supplied for you, because there is no statement line behind this entry. Two legs or more, netting to zero per commodity.
The replacement’s date, YYYY-MM-DD
Hledger tcode
Responses
Section titled “Responses”Successful Response
object
The entry.corrected audit action’s event sequence
The mirror that was posted
object
object
Signed integer micro-units (millionths) as a base-10 string; never a JSON number.
object
The entry that now stands in the original’s place
object
object
Signed integer micro-units (millionths) as a base-10 string; never a JSON number.
object
object
Example
{ "entry": { "postings": [ { "amount_micros": "-12000000" } ] }, "replacement": { "postings": [ { "amount_micros": "-12000000" } ] }}Bad Request
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Unauthorized
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Forbidden
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Not Found
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Conflict
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Precondition Failed
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Unprocessable Content
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Internal Server Error
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Service Unavailable
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}