Eleven lines, nothing deleted
- Deposit charged: €1,800, charge
ch_7741. - 14 panels reserved, reservation
R-552. - Crew B booked for 12 May, booking
CB-0912. - Invoice
INV-0418issued for €1,800 and emailed to the customer. - Permit application filed with the municipality, reference
2026/7731, filing fee €95 paid by the installer. - Two days later, roof survey failed: the rafters cannot carry the panels.
- Application
2026/7731withdrawn. Filing fee not returned, €95 written off. - Credit note
CN-0051issued againstINV-0418, minus €1,800. - Booking
CB-0912released. - Reservation
R-552released. - Refund of €1,800 issued against
ch_7741.
That is contract SOL-3127 at a home-solar installer, as its records show it, and the deal is dead. Yet every line from before the survey is still there. The customer's card statement shows the charge and the refund. The accountant has an invoice and a credit note. The municipality has an application marked withdrawn. Each of the last five lines is a Compensating Action: a new business operation, committed like any other, that cancels the effect of a step that already committed. Saga decides which of them run, in what order, and why the survey came last. This article is about designing one of them.
The installer's first version did something cheaper: when a survey failed, it deleted the contract's rows. The database then said SOL-3127 had never existed, while the customer's €1,800 was still gone and nobody had a record to answer her with. A rollback works on a change a transaction has not committed yet. These steps had committed two days earlier, in different systems, some of them another company's. (An undo inside one process, before anything has reached anyone else, is an easier problem, and Command shows what it has to keep.)
Rarely the step's mirror image
The refund looks like the charge with the sign flipped, yet the customer's statement carries both lines and the card processor may keep its fee. The booking is released in one line, but while it stood, two customers who asked for 12 May were told the date was taken, and no release reaches them.
The invoice shows the gap best. Tax rules in many countries require invoices to be numbered in sequence and kept once issued, so INV-0418 cannot be deleted and its number cannot be reused. Its undo is a different document: a credit note with its own number that cites the invoice. Accounting decides what this undo looks like, not whoever wrote issueInvoice.
When there is no undo to write
The permit filing is where the undoing runs out. The application can be withdrawn, which stops the municipality working on it, but the fee is gone. The invoice email had also told the customer to expect a crew on 12 May, and no operation un-sends an email. A step like this gets a making-amends action: do what can still be done and make up for the rest. The installer withdraws the application, absorbs the €95 rather than taking it out of the refund, and sends a second email saying what happened and why.
Here the business accepts €95 and a clear email as the price. If it would accept no price, the step has no compensation at all, and Saga deals with where such a step goes under the name pivot. Some steps need no compensation either: the read-only survey changed nothing, and only retriable steps follow the saga's point of no return: they are retried until they succeed, not undone.
What the undo needs from the step before it
Every compensation in the ledger names something: ch_7741, R-552, INV-0418. An early version of the deposit step stored deposit_paid: true, which was enough for the screens and useless for the refund, since a processor refunds a charge, not a customer. Without the id, someone is searching a month of transactions for €1,800.
So a forward step's job includes saving what its undo will need: the id, the amount, who it was for. If the process crashes before that save, the step is in doubt, which has its own section below.
The forward step saves the charge id on the contract, and the compensating action reads it two days later to refund that exact charge.
Safe to repeat, and handed on when it cannot finish
If the refund call times out, the compensating action cannot tell whether it went through, so it asks again. That is why a compensation has to be idempotent: running it twice must leave the same result as running it once. Many processors refuse to refund more than was charged, so a second attempt may come back as an "already refunded" error, which the compensation has to read as success or a finished refund looks like a failed one.
The credit note has no outside party protecting it. A retry that issues CN-0052 as well would record a second €1,800 credit that nobody is owed. So billing accepts each reversal under one key, SOL-3127-invoice, with a unique constraint on it, and a second request gets back the note that already exists. Idempotent Consumer treats duplicate delivery in general; in an orchestrated saga, what keeps asking after a crash is usually a Process Manager.
Retrying helps only with failures that can pass. If the processor rejects a refund because the customer has closed the account behind the card, the installer still owes the money. When retries run out, the compensation becomes a task for a person: the customer, the amount, the charge id and the rejection, on a queue someone in accounts actually reads, with the contract showing as unfinished until they close it, perhaps with a bank transfer. If the failure only reaches a log, the customer stays €1,800 out of pocket and nobody knows.
A step still in doubt
Saga compensates the steps that committed. If nobody can say whether a step did, a compensation can overtake the very command it is meant to cancel:
- The contract service sends
BookCrewto the crew scheduler, which is backed up, and the call times out. - The saga treats the timeout as a failure and sends
ReleaseCrew. - The scheduler finds no booking to release, answers that there is nothing to do, and the saga marks the step compensated.
- Forty seconds later, the scheduler reaches the delayed
BookCrewand books Crew B.
The contract closes, and on the booked date a crew and its scaffolding arrive at the house of someone who is no longer a customer, because the compensation meant "cancel the booking" when it needed to mean "no booking with this reference may exist, now or later". So the scheduler keys both commands on one reference, SOL-3127-crew, unique in its table, and handles each in one transaction on that row. ReleaseCrew for a reference it has never seen records that reference as cancelled. BookCrew then finds the row and declines. If BookCrew got there first, ReleaseCrew frees the crew. Whichever arrives second sees what the first one wrote.
Do not count on an outside system keeping a marker for you. There, the compensation first finds out what happened, by looking the operation up under a reference you sent with it, or by repeating the request with the same idempotency key where the API offers one, and compensates once the answer is known. A lookup that finds nothing is not yet that answer, because the delayed request can still land, so look again once the longest delay that system states has passed, and if it states none, ask a person. A municipal portal that offers neither sends the question to a person.
Fail the survey, repeat the credit note
In Saga Compensation Flow, draw the deposit, the invoice, the permit and the survey, each with its success decision, and give each compensation a Process node named for what it really does: "Issue credit note", not "Undo invoice". Then break it by hand. Fail the survey and check that all three compensations are on the path. Then run the credit note twice, and write on its node what stops a second note being issued. If you have nothing to write, the undo is not designed yet.