Skip to content

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.

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.

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.

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.

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
Separate invoice, provider and customer outcomes

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.

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.

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.

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.