# Quotes, invoices and payment records — local guide

**v0.11 update:** The portal/PDF guide supersedes the historical code-login and print-only steps below. Download private generated PDFs with saved content/current summaries; review exact quote content before accepting or declining. Older permanent customer codes are revoked on upgrade. Current recovery writes format 8 and supports pinned formats 1–7. [Current guide](PORTAL-AND-PDF-GUIDE.md).

Version 0.5 adds an explicit document lifecycle to the two fictional businesses. Use invented records only. All sharing is inside the local customer portal; no email, payment charge, refund, tax filing or external delivery occurs. These are labelled demonstration documents, not configured UK business invoices.

The new screens build successfully and their API workflows are tested. They have **not been checked interactively** because the earlier browser discard dialog remains stalled and Sandy is away. The steps below describe the implemented workflow for a later check, not a completed screen demonstration.

## Make and share a quote

1. Open or create a job for the intended customer. Choose **Create quote**.
2. Add descriptions, quantities and unit prices. Quantities support up to three decimal places. Each line rounds half up to a penny; the subtotal is the sum of those line totals. The demo VAT amount rounds half up once on the subtotal. Unit prices and saved totals use integer pence.
3. Set the document date, optional valid-until date and customer-visible notes. Save the draft.
4. Open **Quotes & invoices**, find its reference and choose **Manage**. A draft is private. **Edit draft** preserves an owner history of earlier saved content and rejects stale versions.
5. Choose **Share in portal** when it is ready. Sharing seals the content and makes it available to that exact customer. Enable that customer's portal separately under Customers if required. No access is granted by matching a name or email.
6. The customer can accept a current shared, unexpired quote in the local portal. Alternatively, the owner can choose **Record customer acceptance** after receiving acceptance outside this demo; the action and optional private note are retained. This is not a legally validated signature flow.

An expired quote cannot be shared or accepted. A cancelled draft remains private. Shared or accepted content cannot be edited in place. Choose **Create revision**, give a reason and edit the new numbered draft. The old snapshot remains available with a superseded label, and its old portal acceptance action fails. Share the new revision and obtain acceptance again. A quote with an active linked invoice cannot be revised/cancelled until that invoice is resolved. Full decline/signature and external acceptance evidence remain separate work.

## Create and issue an invoice

From an accepted quote, choose **Create draft invoice**. Repeating that conversion returns the same active invoice; it does not create another charge. You can also select an existing job at the top of Quotes & invoices and choose **New draft invoice** without making a quote first.

Review the draft's line items, notes and optional due date. It remains private and is excluded from invoiced/outstanding totals until **Issue locally** is confirmed. Issuing seals its content and makes it visible in the exact customer's local portal. No email is sent. Invoice edits never change the accepted quote snapshot. The owner must review any difference between the accepted quote and the invoice before issue.

**Existing v0.4 invoices keep their access.** The old version made invoices visible immediately. On forward upgrade, those invoices are explicitly retained as issued, with their original reference, content, receipts and portal visibility. Their original creation time is retained as the migration's issue marker; it is not evidence of a historic email or real delivery. Only newly created invoices use the new private-draft step. Existing local sessions remain valid during this schema upgrade. A pending operation ID from the older code fails closed if its fingerprint differs; review the saved receipt/history rather than submitting another payment blindly. Fresh-folder recovery still rotates/revokes access as documented separately.

References are reserved per business in a transaction and never reused by cancellation/void. Quote revisions and replacement invoices receive their own references. Custom/year-based reference formats are not yet provided.

## Plan deposits and staged payments

1. In an invoice's Manage view, choose **Plan deposit / stages** before recording receipts.
2. Use **Build deposit + balance** with a percentage, or enter fixed stage amounts and due dates. Add stages as needed, up to twelve.
3. The stage amounts must add up exactly to the invoice total. Percentage deposits round half up and the final balance receives the exact remaining pennies.
4. Save the plan. Before any stage is requested or any receipt exists, you can replace it or clear the unused plan. Clear it before changing the invoice total.
5. Issue the invoice if it is still a draft. Choose **Request locally** beside an unpaid stage. Its **View / print** link shows that stage within the same invoice.

A deposit/stage request is **not another invoice, receipt or extra revenue**. Requesting a stage never records money. The print view distinguishes a planned stage from a requested one. A void/cancelled invoice is not payable through an old stage link.

The plan locks after a request or any recorded receipt. That prevents replacing paid/requested history. Negotiated replanning after a request, automatic reminders and stage-overdue alerts remain outstanding; dates are displayed for manual follow-up. One invoice's stages cannot be used to allocate another invoice's receipts.

## Record money already received

Choose **Record payment**, enter the amount, received date, method and optional private note. Received dates cannot be after today in Europe/London. Quote expiry and default document/receipt dates also use London, even if the host uses UTC; document/validity/due dates are date-only calendar values. This records an invented receipt; it does not collect money. A general receipt fills the earliest unpaid stages first. **Record receipt** beside a stage allocates only to that stage and cannot exceed its remaining amount.

There is one receipt ledger. Invoice balance and stage paid/partial/requested/planned state are calculated from unreversed receipts and allocations. There is no separate “mark paid” flag that could count the same money again. The server rejects overpayment and checks current balances in the same transaction as the write. Transport retries use the same operation ID; a successful write followed by a failed refresh must be reloaded before another change.

Customer history, job cost summaries, the overview and the portal use the same net-receipt basis. Draft, cancelled and void invoices do not add to invoiced/outstanding totals. These totals are operational records, not an assertion of accounting revenue, profit, recoverable VAT or tax treatment. A job's work stage remains manually managed: paying one of several invoices does not automatically mark the job complete.

## Correct or close a document

| Situation | Supported local action |
| --- | --- |
| Quote or invoice draft no longer needed | Cancel it with a reason. Keep the record/reference/history; a never-shared draft stays private. |
| Shared/accepted quote needs new terms | Create a revision with a reason. Keep the previous snapshot and block its old acceptance action. |
| Issued invoice with no net receipts needs cancellation | Void it with a reason. Retain the original document and stop counting it as payable. |
| Unpaid issued invoice needs corrected content | **Correct with replacement** voids the old invoice and creates a linked, newly numbered private draft. Edit/review/issue that replacement separately. The original snapshot stays unchanged. |
| A receipt entry itself was wrong | **Correct recording error** retains the original entry as reversed. Enter an optional replacement amount/date/method/private note in the same save, or reverse only, with a reason and explicit confirmation. |
| A real receipt needs to be refunded, credited or charged back | Not implemented. Keep the actual receipt. Obtain an appropriate settlement/accounting decision; do not reverse a true receipt merely to unlock a void. No money moves here. |

Payment corrections are atomic: an invalid replacement leaves the original receipt, allocations, balance and version unchanged. A valid correction recalculates stages and net totals without deleting the original. Owner history retains private reasons; the customer view shows the reversal without exposing private payment notes or internal audit history.

Paid invoices cannot simply be voided or replaced. Credit-note numbering/tax treatment, refund settlement, chargebacks, discounts/retentions and negotiated payment-plan changes remain explicit gaps. They require a defined product/accounting policy before real use; this milestone does not invent one.

## History, conflicts and printing

Manage includes saved document history, prior/current snapshots and reasons. Open the private printable quote/invoice or payment stage with **Open printable** / **View / print**. **Print / save PDF** opens the browser's print dialog; actual printing or saving a PDF is a separate action and has not been tested in this milestone. No generated private PDF is exposed through a public uploads path.

If another window changes a record, leave or discard the current form deliberately, then choose **Reload record** and review the current version before retrying. Keep unsaved form content until you decide what to discard. The app does not silently overwrite a newer document or force a page update. A newer build's browser update/offline behaviour still needs its own PWA milestone.

## Upgrade and backup compatibility

The invoice migration is transactional and preserves existing rows/relationships. The normal empty demonstration was snapshotted with the preserved v0.4 recovery tool before its upgrade. For any other saved v0.4 dataset, stop the old app and retain a known-good v0.4 backup before opening the new code. Keep the old code archive too.

Version 0.5 introduced recovery format 2. The current v0.6 creates **format 3**, supporting the pinned v0.4 format 1, pinned v0.5 format 2 and current format 3 with strict schema/content validation. A v1 archive is upgraded only inside the new private restore folder, and its source archive/folder remains unchanged. Format/schema validation has not been relaxed to accept arbitrary databases. Older code cannot read the newer format or safely open a migrated folder: rollback means restoring the old snapshot with the matching old code into another fresh folder, never downgrading in place.

All owner passwords/sessions/portal grants are deliberately changed or revoked in a recovered copy, just as in v0.4. See [the recovery guide](BACKUP-AND-RECOVERY.md). The local tool remains whole-demo, unencrypted and unscheduled; it is not production backup approval.

## Evidence and next work

Tests cover draft/privacy transitions, expired/cancelled/superseded quotes, current-customer acceptance, sealed/replacement invoices, exact fractional line and VAT totals, unique numbers, payment/stage/correction retries and concurrency, cross-business/customer access, CSRF/origin checks, v0.4 upgrade visibility, strict old/new recovery and two-business loss/recovery with corrections intact. The current totals and proof files are in [VERIFICATION.md](VERIFICATION.md).

The full white-label objective continues beyond this milestone. Read [the parity register](FULL-PARITY-REGISTER.md) for source-evidenced gaps, integrations and decisions. The v0.6 website/branding checkpoint is described in [its owner guide](WEBSITE-AND-BRANDING.md); the next recommended stage is private job photos and controlled gallery publication. Every new v0.5 screen still needs legitimate browser verification later.

Version 0.6 adds optional published business particulars, document footer/terms and saved logo identity. Existing drafts, issued documents and accepted-quote conversions retain their original business snapshots. See the website guide before changing these defaults.