Retainage and lien waivers

Retainage is money withheld from a payment until the work is far enough along. LEDGER accrues it on both sides of the job: what you hold from your subcontractors, and what the owner holds from you. Open Retainage in the LEDGER rail.

This is financial arithmetic that ends up in a contract dispute, so it is worth reading the model before you set a rate.

The retainage schedule

One schedule per agreement. A commitment has one, a prime contract has one. There is no per-line override and no "header rate plus exceptions" mode. A commitment's retainage terms are one clause in one agreement.

A schedule has two ladders: one for work completed, one for stored materials. Each ladder is a list of rungs, and a rung has two numbers:

Rung field	What it is
Threshold	The cumulative-complete point the rung ends at, in basis points
Rate	The withholding rate applied to amounts billed inside that rung

A flat 10% schedule is a single rung: 10% withheld through 100% complete. A ladder of 10% to 50% complete then 5% thereafter is two rungs: 10% through 5000 bps, then 5% through 10000 bps.

Rules the product enforces on a ladder:

• At least one rung, at most 10.
• Rates between 0% and 100%, in whole basis points.
• Thresholds must rise, and the last one must be 100% complete.

Thresholds measure the line, not the agreement

A rung's threshold is a percentage of the schedule-of-values line the amount is billed on, not of the whole commitment. A line that is 60% complete has crossed a 50% rung even if the commitment as a whole is at 20%.

Crossing a threshold is never retroactive

When billing crosses a rung, only the dollars billed above the threshold get the new rate. Dollars already billed under the old rate are never revisited. The accrual window always starts where the previous cumulative figure ended.

Rounding

Rounding is half-up, applied per rung rather than once on the total, so a rung's accrual depends only on that rung's dollars. Every figure is a whole number of cents; nothing is held as a decimal.

Setting the terms

The schedule is snapshotted at first billing and is fixed after that:

Billing has already started on this commitment, so its retainage terms are fixed.

Set it on the first invoice against a commitment. Doing so requires administrator access on Invoicing:

Setting the retainage terms for a commitment requires Invoicing administrator access.

If no schedule is stated and the commitment carries a retainage rate, a flat ladder is built from that rate. If neither exists, nothing is withheld.

Sending an explicit empty schedule means "this agreement holds no retainage", which is different from omitting the field. Because the schedule is permanent after first billing, that distinction matters.

How it accrues on a subcontractor invoice

For each line, in this order:

1. Work completed this period accrues against the work ladder, starting from the work already completed on that line.
2. Stored materials accrue against the stored materials ladder, starting from where the work cursor ended after step 1.

The two ladders share one completion cursor and apply their own rates.

Retained to date is the previous retained plus what accrued this period, on each ladder, added together.

How it accrues on an owner pay application

The work ladder behaves the same way. Stored materials do not, and the difference is deliberate.

On the owner side, materials are a standing balance. When the balance goes up, the increase accrues against the materials ladder. When material is installed and the balance goes down, the retainage held against it transfers onto the work ladder rather than being released.

In a period where material is installed, the line's materials retainage figure is negative. That is the transfer, not a release. The held amount can never go negative, and emptying the balance transfers out exactly what was held.

The reason for the asymmetry: if the owner side rolled materials into previous work the way the subcontractor side does, a pallet that sat untouched for a month would re-rate itself downward as work climbed the ladder. That is a silent retroactive un-retention, and it is not allowed to happen.

Held, released, and the total

For any chain:

• Accrued to date is work retained to date plus materials retained to date.
• Released to date is what has been released.
• Currently held is accrued to date less released to date.
• Total earned less retainage is total completed and stored less currently held.

Recording a release

A release is a dollar amount somebody records. It is never a recomputation of the ladder. Releasing retainage does not change any rate, any threshold or any accrual.

Record it on the invoice, from that invoice's own screen. It requires Invoicing ADMIN, the sharpest gate in the module, because it moves money that was being withheld.

Two rules:

• A release cannot be negative. Withholding more is an accrual, not a release.

• A release cannot exceed what is held:

  This release is more than the retainage held on this commitment.

The invoice has to be editable to take one, so it cannot be recorded on an approved invoice or inside a closed billing period.

On the owner side, the release travels on the application, and the owner's counterpart travels as a certified release when the certification is recorded.

The retainage ledger

The Retainage screen shows both sides on one page rather than behind tabs, because a project accountant reads them against each other.

Side	What it holds
Payable	Retention you hold from your subcontractors, per commitment
Receivable	Retention the owner holds from you, per prime contract

Nothing on this screen computes. Every figure was derived by the billing engine and summed server-side; the page renders and does not add.

Each row resolves one of three ways:

Row state	Meaning
Counted	Figures from the latest counted invoice on that chain
Not billed	The commitment has live invoices but none counted yet, so nothing has accrued. This is a real answer, not an absence
Failed	The read did not answer. The row says so rather than showing zero held

Only the latest counted invoice per chain is read, because the cumulative columns already carry the chain's whole history. Summing invoices would double count.

Totals are whole or unavailable. One failed row makes that side's totals unavailable rather than a sum of what happened to load.

Advisories

Two facts appear beside rows, and both are statements rather than instructions. Nothing on this screen releases retainage, proposes an amount, or executes a payment.

• Fully billed means total completed and stored equals the scheduled value.
• Threshold passed means a line's current marginal rate is below the ladder's opening rate, so a lower rung is now in effect.

The owner-held figure beside the payable side is context. The platform enforces no pay-when-paid condition, and a subcontractor release does not wait on the owner in this product.

Reading the ledger needs Invoicing READ_ONLY. Commitment and contract names are joined only if you also hold READ_ONLY on those tools; without it the figures still render and the name is marked withheld, which is kept distinct from a read that came back short.

At most 250 chains are read per side. Past that the side refuses rather than producing a partial total.

Lien waivers

Lien Waivers in the rail records which releases exist for a billing cycle and what state each is in. The note at the top of the surface says what it is:

Struxen records which releases exist and what state each is in. It does not produce the waiver document, and it does not check one for you. Nothing here blocks an approval or a payment.

There is not one dollar amount on this screen, and there must not be. A release is evidence about a payment, never the payment.

Types

Type	Label
conditional_progress	Conditional progress
unconditional_progress	Unconditional progress
conditional_final	Conditional final
unconditional_final	Unconditional final

Conditional means contingent on the payment clearing; unconditional means not. Progress covers one cycle; final closes the commitment out. The platform asserts nothing about what any of them means in law, in any jurisdiction.

Statuses

Status	Meaning
Not requested	No release has been asked for
Requested	Asked for, not yet in hand
Received	The document arrived

From	To
Not requested	Requested, Received
Requested	Received
Received	Requested

There is no edge back to Not requested. Received to Requested is the correction path, and it is the only way out of Received.

Status is entered, never derived. The product cannot promote a conditional release to unconditional, because that would need a record of payments received that the platform does not have.

Received shows an information badge, never a success tick. A green tick beside a release reads as "this vendor is clear", which is a legal conclusion the platform does not draw. It knows a document arrived, not what it covers.

A row with no record reads None recorded as a stated sentence rather than as a blank cell, because an empty cell in a release column reads as a clean one and those are opposite facts.

Each record can carry notes and a free-text form label, which is stored verbatim and never interpreted. Superseded receipts are preserved rather than overwritten, and at the cap of 20 the write is refused rather than the oldest being pruned.

Recording a waiver needs Invoicing STANDARD plus the submit permission, the same pairing as entering a subcontractor invoice. It is deliberately not an administrator action.

The pay-application package carries a waiver column, rolled up per commitment and cycle as none recorded, requested, partial or received.

Limits

Limit	Value
Rungs per ladder	10
Chains read per ledger side	250
Superseded receipts per waiver	20
Waiver note length	1,000 characters
Form label length	60 characters

Troubleshooting

Setting the retainage schedule is refused. Either billing has already started on that commitment, in which case the terms are permanent, or you do not hold administrator access on Invoicing.

A release is refused. It is negative, or it is larger than what is held, or the invoice is approved or in a closed period.

A retainage ledger row says the read failed. That chain's latest counted invoice or its billing period could not be read. The side's totals are withheld too, on purpose.

A commitment name is missing from the ledger. You do not hold Commitments READ_ONLY. The retainage figures are still correct and still shown.

The held figure on screen disagrees with the ledger. A release recorded on a draft invoice shows on that invoice immediately, but the ledger reads only counted invoices. If the draft is never approved, the release never reaches the ledger.