Invoicing and settlement
An invoice records a claim against a customer. Toolora links that claim to accepted commercial work, reserves the selected billing basis and preserves document history. Accounting handoff, customer delivery, bookkeeping, customer payment and authority payout have separate evidence. A numbered invoice or completed project does not establish settlement.
Commercial authority owns accepted scope and source provenance. Planning, execution and review owns performed work and operational completion. Subcontractor awards create supplier commitments; they do not create customer invoice revenue or prove that a supplier has been paid. Payroll also retains its own time handoff.
Records and evidence
Section titled “Records and evidence”| Record | What it establishes | Separate fact |
|---|---|---|
| Accepted billing-basis row | Accepted source amount, source identity, invoiced/reserved amount and remaining amount | Work-order allocation or approved time alone does not create this authority. |
| Invoice and lines | Customer, project/quote provenance, currency, net/tax/gross amounts and selected source consumption | Draft creation is already a reservation; it is not accounting transfer. |
| Recipient, deduction and payment-account snapshots | Invoice-specific recipients, allocation provenance and payment instructions | Changing customer defaults does not rewrite issued evidence. |
| Accounting export and mutation receipts | Requested mode, processing claim, provider references and observed outcome | Exported/numbered does not mean booked, emailed or paid. |
| Send request and frozen delivery | Reviewed PDF hash, selected recipient, saved PDF bytes and delivery outcome | Provider acceptance and confirmed receipt have different meanings. |
| Credit and replacement links | Reversed source quantities/amounts, reason and original/correction history | Creating a credit does not prove provider settlement or authority correction. |
| Invoice status snapshot and payment feed | Observed balances plus retained provider payment events and coverage | Missing payment rows do not establish zero payments. |
Capability and resource checks apply to each privileged operation. The editor’s ordinary database access instead uses row-level security. Company-scoped cache keys and queries retain the selected tenant. A linked project is not permission to change another company’s invoice.
Create an invoice from accepted work
Section titled “Create an invoice from accepted work”The project invoice action requires invoices:write and the selected company’s
live project. It loads the current basis and linked historical invoices. Imported
invoices without reconciled basis links block new billing rather than presenting
the accepted quote as entirely unbilled. Project and quote relationships
retain their source meaning; a source-only historical quote is not accepted billing
authority.
Partial billing selects explicit basis rows and amounts. Final billing selects the remaining eligible basis when no narrower selection is supplied. Amounts must be positive and cannot exceed the row’s remainder. A reasoned manual adjustment is a separate invoice line; it does not rewrite the accepted source. Monetary calculations round the persisted amount to two decimals. Currency and tax treatment belong to the selected lines and invoice; different currencies must not share one monetary total.
The service-only create_project_invoice_from_basis transaction locks and rechecks
source consumption. The current wrapper verifies both amount and fixed-price
quote-hour allocation against the persisted invoice line. Header, lines, deduction
rows and source reservations commit together or roll back. Concurrent invoices
cannot each consume the same remainder. Draft deletion releases the amount and
proportional quote hours; restoration consumes them again and fails if that basis
has since been used elsewhere.
The request does not provide a general client idempotency key: the API generates a new invoice ID. Transactional creation is not acknowledgement replay. After a lost response, inspect the project’s invoice list and remaining basis before retrying. A repeated partial request can otherwise create another invoice while enough basis remains. A stale-basis conflict requires a reload and a new deliberate selection.
The new project draft leaves its issue date unset. Staff complete and review the invoice before handoff. For fixed-price eligible labour, proportional accepted quote hours remain explicitly estimated provenance. Running-account hours and performed-hour verification are different facts. The draft can retain incomplete hours; the handoff boundary requires the supported verified whole-hour values. Configured rate periods, invoice date, recipient allocation/version and dwelling checks are separate gates. This workflow does not define tax eligibility or infer performed hours from a price or percentage. See ROT and RUT allocations.
Save and review the draft
Section titled “Save and review the draft”The editor calls save_invoice_draft with header changes, line values, removed
line IDs and the updated_at revision it read. This function uses the caller’s
permissions under RLS. It locks the invoice, checks the revision and line ownership,
writes rows, then writes the header and returns the new revision. A stale revision
refuses the whole save; it does not silently merge another editor’s changes.
Only supplied and explicitly removed lines participate in that save. Existing immutability triggers continue to govern issued or export-locked records. Dating an invoice can freeze commercial rows written in the same transaction. A revision error calls for retaining the local draft, loading current data and resolving the difference. A lost successful response can also make the next save stale; reload before deciding whether another write is needed.
The unsaved customer preview is a read-only rendering of editor values. It is not
the final, numbered document approved for delivery. The final document requires a
successful Fortnox draft_only handoff, its invoice number, issue-date evidence,
recipient and payment instructions. The API returns that PDF with a SHA-256 ETag.
Staff review that exact document before send. Data completeness can still prevent
rendering even when send status says the final-document stage has been reached.
Hand off without assuming delivery or bookkeeping
Section titled “Hand off without assuming delivery or bookkeeping”The current Fortnox path uses a provider-neutral accounting interface backed by Toolora’s in-process adapter. The shared connector owns credential/rate-budget and read-feed contracts; its adoption is not a completed customer-invoice write cutover. Accounting integration owns the wider contract. This article describes existing calls, not authority to add direct provider calls.
New export rows default to draft_only. The database handoff resolves line accounts,
checks invoice/deduction readiness and captures/locks the relevant source. The worker
claims queued exports, performs provider calls outside the database transaction,
and writes provider references under its claim token. It creates an unbooked,
unsent Fortnox invoice draft; book_and_send remains a historical stored value, not the current default delivery contract.
A number is a provider identity, not proof of bookkeeping.
Mutation receipts distinguish confirmed results from attempted calls whose outcome is uncertain. A confirmed receipt can repair local reference writeback after a lost acknowledgement. An attempted mutation cannot safely be treated as an instruction to create another provider invoice. Processing claims, retry/backoff and dead/error states protect the queue; they do not make the external call atomic with local persistence. Reconcile uncertain outcomes through the existing operation and provider identity before another write.
ROT/RUT recipient submission to the provider is also separate from authority payout. The in-process worker prepares its supported tax-reduction records during handoff; that does not prove an authority application was approved, paid or subsequently corrected. The exact connector/accounting mode and external receipt remain necessary for any such conclusion.
Send the reviewed customer document
Section titled “Send the reviewed customer document”The browser supplies an Idempotency-Key and the reviewed hash in If-Match.
The API checks invoices:send, invoices:update and the company’s live numbered
invoice. A new request also requires a matching final PDF. Reusing a key for a different invoice or hash
conflicts. A repeat of the retained key/hash can return its saved request before re-rendering
the current PDF. It does not create another delivery. The send-request RPC prevents
competing active requests; the worker rechecks the expected document before creating
its delivery.
The delivery row freezes recipient/sender, number, payment reference, PDF bytes and hash before the email provider is called. A conditional queued-to-submitting claim selects one sender; the provider key identifies that retained delivery. Customer send and provider invoice handoff retain separate records and outcomes.
Provider acceptance records submission, while a delivery webhook or staff-confirmed
receipt can record delivered. The staff confirmation preserves its actor/source
and sends no new message; it is a staff assertion, not a provider webhook or customer
signature. An interrupted/ambiguous submission becomes submission_unknown and is
not automatically sent again. A missing acknowledgement is not evidence that the
customer received nothing. Poll the saved request/delivery and investigate before
attempting another send. A failed document-hash check requires a fresh review.
The retained sent PDF is evidence of what was delivered. Re-rendering today’s invoice
is a different operation. Fortnox Sent=false does not invalidate a Toolora delivery
receipt, and a Toolora receipt does not imply Fortnox bookkeeping or payment.
sequenceDiagram participant S as Staff editor participant DB as Database participant W as Accounting and delivery workers participant F as Accounting provider participant C as Customer S->>DB: Create draft, reserve exact accepted basis S->>DB: Save header and lines at expected revision S->>DB: Request draft-only accounting handoff W->>F: Create unbooked provider draft with receipt F-->>W: Number and observed provider result W->>DB: Save reference under processing claim S->>DB: Read final PDF, then request send with hash and key W->>DB: Freeze PDF and recipient, claim delivery W->>C: Submit retained document W->>DB: Record accepted, delivered or uncertain outcome F-->>W: Separate payment/feed observations W->>DB: Retain projection and coverage
Correct the appropriate record
Section titled “Correct the appropriate record”An unnumbered editable draft can be changed under the editor’s revision/immutability rules. Copying creates another draft; it is not a reversal of issued history or proof that the copied work remains billable. A basis-backed draft’s soft deletion and restoration have their own reservation rules.
For a successfully transferred unbooked ordinary invoice, the cancellation path requires a reason and reserves the correction against competing customer send. It checks current provider state, refuses bookkeeping/payment or incompatible history, and requires confirmation that a customer with a delivered copy has been informed about replacement. The provider cancellation is read back before local cancellation releases source amounts and proportional quote hours. If provider cancellation succeeds but local acknowledgement fails, reconcile that operation; do not edit the old issued lines to manufacture a replacement. Invoice, export and delivery history remain linked evidence.
A booked original uses a credit. invoices:cancel plus company/resource scope protects
the API. For a new credit request, it refreshes provider state and requires a booked,
uncancelled original. A retained request can replay its result without repeating that
new-request precondition. The credit has an explicit reason and idempotency key.
Non-deduction invoices support full or selected-quantity partial credits, constrained
by what remains creditable. The negative document, original-line links and export
queue are created atomically. Locking the credit releases the exact associated
billing-basis amount; this local release is not provider payment or credit settlement.
Reverting an eligible failed, unexported credit reconsumes its released basis.
ROT/RUT invoices require full credit. API checks and deferred database guards refuse partial quantities/incomplete deduction reversal. A credit contains negative reversals, not a new positive deduction claim. The corrected-replacement function requires the original/full-credit relationship, verified draft-only credit handoff and fresh unbooked/unsent provider readback. It atomically creates one idempotent replacement, preserves project/quote/basis provenance, reconsumes released basis and recalculates deductions from retained labour evidence. A full credit does not itself prove that the authority’s application or payout was corrected.
Reconcile payment evidence
Section titled “Reconcile payment evidence”The invoice list’s operational state uses retained status/balance observations. A
numbered invoice with missing or stale evidence is labelled Kontrollera betalning.
Current code applies a 48-hour status window using the supplied day’s end; this is
an operational summary, not a register-completeness proof. Total discrepancies can
produce Stäm av betalning. The customer/authority split depends on observed
Total, TotalToPay and Balance. Those fields have different meanings: partial
payment can change Balance while TotalToPay remains the original payable amount.
Credit totals and paid-to-date helpers are also operational calculations. The local credit helper classifies numbered, non-draft/non-cancelled credits from retained states; that predicate alone is not fresh evidence of actual provider bookkeeping or credit settlement. Do not use a face-value subtraction as proof that a linked credit has paid the original invoice.
The stricter invoice reconciliation reader uses the active tenant-owned connector mapping and a current count/hash parity proof for the payment register. Proof expiry and feed revision must agree. Individual payment rows, unresolved associations, unsupported shapes and tombstones retain their own meaning. Missing rows without that coverage do not establish zero payments.
When coverage permits reconciliation, it live-reads the booked invoice and each
Toolora-linked credit, checking provider/company identity, document reference,
currency and credit-parent relation. The pure reconciliation requires fresh invoice
observations (within 30 minutes, with a five-minute future tolerance), exact minor-unit
amounts, known booked payments without write-offs, matching currency and invoice observations
no older than the payment observations. Amounts must explain the observed balance. Reduced
payable amounts and other non-payment adjustments require separate evidence and are
not silently treated as customer payments. Contradiction or incomplete coverage
returns unavailable and forbids balance inference. Reads retain bounded credit and
payment limits rather than claiming an exhaustive result after truncation.
Credits are separate documents: sum their remaining balances once. A credit already settled against the original has zero remaining balance; subtracting its face value again would reduce the claim twice. The reader’s scope is the requested invoice and Toolora-linked credits, not every possible external document or all future events. A verified result describes that observed set and time, not complete project or company financial closure.
Example and recovery
Section titled “Example and recovery”A synthetic accepted basis contains 80,000 SEK net. A partial draft consumes 20,000; 60,000 remains before provider transfer or customer delivery. With an illustrative configured 25 percent tax rate, the invoice total is 25,000. A verified 10,000 payment leaves an observed invoice balance of 15,000. A credit reversing 4,000 net at the same illustrative rate has an open balance of −5,000, which makes the combined receivable 10,000. Once that credit is settled against the original, the original balance becomes 10,000 and the credit balance becomes zero; the combined claim remains 10,000.
These payment facts do not decide whether work is complete. Staff project readiness, customer delivery acceptance and UE commitment closure use the execution workflow’s separate gates. A completed project can retain billing or payment work; a paid invoice can belong to unfinished work. Purchase costs, supplier payments and margin completeness remain with purchase-cost allocation and financial reconciliation.
| Situation | Recovery and retained evidence |
|---|---|
| Lost project-draft response | Reload invoices and remaining basis; creation has no general caller-key replay. |
| Concurrent source consumption | Reload the locked remainder; do not reuse an obsolete billing selection. |
| Stale editor revision | Preserve local input and resolve against the current revision; the save rolls back together. |
| New PDF/hash after review | Review the new final document before supplying its hash; draft preview is insufficient. |
| Uncertain accounting mutation | Inspect mutation receipt and provider reference; do not create another invoice blindly. |
| Uncertain customer submission | Retain frozen delivery and investigate provider/recipient evidence; automatic replay is stopped. |
| Cancellation/credit/replacement fails | Preserve original chain and inspect which local/provider step committed before retrying its own operation. |
| Missing/stale payment evidence | Refresh through the existing read path; incomplete register coverage remains unavailable. |
| Operational close refused | Resolve the operational blocker; invoice/credit/payment state does not bypass it. |
The transaction reference compares invoice creation, draft revisions, credit/send keys and payment-page rollback with the separate provider boundary.
Verification scope
Section titled “Verification scope”The delivery PR identifies the focused synthetic tests, current candidate CI and retained earlier receipts. Previously observed draft-only handoff, Toolora delivery, non-ROT credits and stale-status refresh prove their named scenarios/versions. They do not prove live ROT replacement, real payment registration, authority reconciliation or required-mode accounting acceptance. Those broader scenarios remain in issue #414. This documentation review performs no new provider write, customer send or delivery acknowledgement.