Set up retainage on a contract

Define the default retention rate that applies to invoices and bills on a project — at the vendor level, the project level, or via a sliding matrix that changes as the project progresses.

When to use this

Whenever a new project (or a new vendor on an existing project) needs retention captured at a non-zero rate. Most accounts set rates at two layers: a vendor-level default that applies to every bill from a particular subcontractor, and a project-level default that overrides it for the customer side of a specific job. For projects with bespoke retention terms — for example 10% until the project is 50% complete, then 5% — use the sliding retention matrix instead of a flat rate.

Prerequisites

  • Retainage installed and a Configuration record in place for the subsidiary
  • An active project, vendor, or customer record to set the rate on
  • Permission to edit the entity record (project, vendor, or customer)

Walkthrough

Walkthrough coming

A step-by-step Scribe walkthrough for this task is being recorded. Track its status in the Scribe register (internal).

Set the project default for AR retention

  1. Open the project (Job) record.
  2. Go to the Retainage subtab.
  3. Enter a percentage in Invoice Retainage % — for example, 10% for a 10% retention rate on every customer invoice on this project.
  4. (Optional) Enter a separate Time Retainage % if billable time entries on this project use a different retention rate to item-based lines.
  5. Save the project. The rate will be applied to every new invoice that links back to the project.

Set the vendor default for AP retention

  1. Open the vendor record.
  2. Locate the Retainage % field — typically on the Retainage subtab on the vendor record, though it may have been moved to a different subtab on a customised form.
  3. Enter the default retention rate for every bill from this vendor.
  4. Save.

You can also set a vendor-style rate at the project level by entering a value in Purchase Retainage % on the project's Retainage subtab. That overrides the vendor default for bills attributed to this specific project.

Cap the retention by amount or percentage

When a contract specifies a maximum retention — for example, retention caps out at $50,000 regardless of how much has been invoiced — set the cap on the project:

  • Retainage Cap % — caps cumulative retention as a percentage of the contract value.
  • Retainage Cap $ — caps cumulative retention as a fixed dollar amount.

Once the cap is reached, subsequent invoices will not have further retention withheld.

Use a sliding (tiered) retention matrix

For contracts where the retention rate changes as the project progresses, switch the project from a flat rate to a sliding matrix:

  1. On the project's Retainage subtab, tick Enable Retention Tiers.
  2. Click Update Retention Tiers — the Sliding Retention suitelet opens.
  3. Enter each tier as a row: the percent-complete threshold and the retention rate that applies in that band. For example:
    • 0% to 50% complete — 10% retention
    • 50% to 90% complete — 5% retention
    • 90% complete onward — 0% retention
  4. Save the matrix. Subsequent invoices will calculate retention by looking up the project's current percent complete and applying the matching rate.

When tiers are enabled, the flat Invoice Retainage % field is ignored on that project.

Override the rate per invoice line

The rate can also be set or overridden line by line on the invoice or bill itself. Each line has its own Retainage % and Retainage Amount column fields — change either and the system recalculates the line's retention. Use this when most lines on an invoice follow the project default but one or two need different treatment.

What success looks like

  • The next invoice or bill saved against the project (or vendor) shows retention populated on every applicable line, totalling correctly in the body Retention Amount field.
  • The project's Retainage subtab updates the Invoice Amount Retained rollup the first time a withholding posts.
  • For tiered projects, the rate applied matches the band that corresponds to the project's current percent complete.

Gotchas

  • Project rate overrides customer rate. If both are set, the project rate wins on invoices attributed to that project. This is by design — projects are the most specific scope.
  • Enabling tiers hides the flat rate field. Once Enable Retention Tiers is ticked, the flat Invoice Retainage % is no longer used. Don't both set a flat rate and enable tiers expecting them to combine.
  • Tier transitions are evaluated at invoice save time. A project sitting at 49% complete will use the lower-band rate even if the invoice you're saving will push it past 50%. If you need the new band to apply, save the percent-complete update first.
  • Sliding matrix can be edited mid-project. Changing the matrix doesn't retrospectively reprocess prior withholdings — it only affects invoices saved from that point onward.
  • AP and AR rates are tracked separately. A project's Invoice Retainage % drives AR retention; Purchase Retainage % (or the vendor's default) drives AP retention. They are independent.
Last Updated: