Proposals & Invoices ยท Article 5.3
Creating an amendment (the 4-step wizard)
The amendment wizard at `/proposals/{id}/amend` walks you through line items, reason, preview, and email โ in that order. Five minutes for a simple change, ten minutes for a complex one. The client doesn't see anything until you click Send on Step 4.
The wizard opens with the current effective scope as the starting point โ that's the original line items if no amendment has signed before, or the line items from the most recent signed amendment if you're chaining (article 7.6). You edit, reshape, add, or remove line items in Step 1; explain why in Step 2; review the rendered addendum in Step 3; and craft the email in Step 4. Everything before Step 4's Send button is private to you.
Quick visual tour
Step 1: Spotted a clause that needs changing in a signed proposal?
Step 2: Click Amend on the proposal โ opens the amendment wizard.
Step 3: Edit the line items that changed. Three highlighted bars show the delta.
Step 4: Send the amendment. Client gets a fresh sign request via email.
Step 5: Client signs the amendment โ you're both back on the same page.
Step by step
Step 1: line items.
Original items appear in the top half, locked and dimmed. Your editable revised list appears below. Each row gets a coloured tag โ green
+ added, amber~ modified, redรขหโ removed, greysameโ so you (and the client, in the diff view) can see at a glance what's changed. The deposit-context banner on the right shows: deposit % from the original contract, deposit cash collected, and what the newamount_duewill be (or refund, if รโ_REFUND). The wizard recomputes after every keystroke.Step 2: reason.
A short text field. Minimum 10 characters for รโ+ / รโ=0, 30 characters when shrinking scope (รโรขหโ / รโ_REFUND) โ the longer minimum encourages you to record the rationale for any reduction, since it's the case most likely to be questioned later. The reason appears verbatim on the addendum PDF and on the client's diff view.
Step 3: preview.
The wizard renders the addendum PDF on the fly via a
/preview-pdfendpoint and embeds it in an iframe. Read it. Confirm the line items, totals, VAT breakdown, and reason all look right. Tick the consent checkbox ("I've reviewed the rendered PDF and confirm it accurately reflects the change") โ Send is disabled until you do. Any edit you make sends you back to Step 1 and invalidates the consent (you'll re-tick it).Step 4: email composer.
Pre-filled subject and body in the proposal's language; both editable. The recipient defaults to the client's email on file but can be overridden (e.g., for an alternate signatory). Click
Send Amendment to Clientto fire the email and lock the amendment from further edits.
The wizard occupies the full screen with a four-step progress bar at the top. The deposit-context banner stays sticky on Step 1. Errors (e.g., "Reason must be รขโฐยฅ 30 characters" on รโรขหโ) appear inline at the top of the relevant step. After Send, you're redirected to /proposals/{id} where the amendment appears in a "Pending amendment" panel with countdown, copy-link button, and a Cancel button.
Why this works this way
The wizard auto-creates (or auto-resumes) a draft ProposalAmendment row the first time you advance past Step 1. From then on, every navigation between steps PATCHes the draft on the server with the current line items and reason. This means closing your browser mid-wizard never loses work โ open /proposals/{id}/amend again and you land back where you left off.
A subtler implementation detail: the wizard creates a "preview" FinalInvoice row attached to the draft amendment, with status=cancelled (not active). The status flips to active only at the moment the client signs, which is when upsert_pending_invoice_for_amendment becomes process_amendment_signed. Two consequences:
1. Your INV-2026-NNNN counter advances when you draft (the number is reserved). If you cancel the draft, the number stays in your book as a cancelled row โ this is normal and matches how German Steuerberater expect to see numbered cancellations in the audit log.
2. The Step 3 preview iframe is rendering against this preview invoice โ it's the exact PDF the client will receive, so what you see is what they get.
If the parent proposal is in in_work status (deposit paid, project running), Step 1 surfaces an extra red 'Refund all' callout button in addition to the line-item editor โ clicking it sets every line-item quantity to 0, drives revised_total to 0, and on client signature the cascade in process_amendment_signed issues Storno + DepositInvoiceCorrection + CreditNote and triggers the Stripe refund. This is the only legitimate path to refund an in_work deposit; direct DELETE on the proposal is rejected with HTTP 409 in_work_requires_amendment (per [D-125]).
Troubleshooting
Keep reading
Proposals & Invoices
When to use an amendment (vs a new proposal vs withdraw)
Three paths exist to change a deal: amend it, withdraw and resend, or start a new proposal. Pick the wrong one and you'll either break the audit trail or scare the client. Here's the decision tree.
Proposals & Invoices
The 4 delta branches: ฮ+, ฮโ, ฮ=0, ฮ_REFUND
Every signed amendment falls into one of four branches based on (a) the sign of the cost change and (b) whether the proposal was already paid. Each branch fires a different document chain. This is the central conceptual map for the entire amendment system.
Proposals & Invoices
Multi-amendment chains: one draft at a time, baseline = current effective
A proposal can have many amendments over its life โ but only one open at any given moment, and each new amendment baselines on the most recent signed state, not the original proposal. Here's how the chain holds together.
Proposals & Invoices
What your client sees when an amendment lands
The client receives an email with a fresh PIN, lands on a PIN-gated page, sees a side-by-side diff of old vs new with totals and a reason, and signs (or declines) โ exactly like the original proposal flow but with the diff baked in.