Construction Payment Application Checker

Check the arithmetic in a construction progress-billing application before another review cycle begins. This Actor compares your cover-sheet totals with schedule-of-values lines, reported retainage, optional approved-change totals and an optional previous certificate. It returns exact differences and the input locations behind them, ready for a reviewer or automation workflow.

This is an independent check of existing numbers, not a billing system or a form generator. It does not determine whether work was performed, whether a change was approved, or whether payment is legally due. You remain responsible for those decisions.

Key features

• Recalculate completed-and-stored amounts and balances for each schedule line.
• Compare the schedule total with the original contract plus net changes.
• Reconcile line-level retainage with the cover-sheet retainage total.
• Check earned-less-retainage, previous certificates, current payment due and balance to finish.
• Optionally compare a supplied list of approved change amounts with the cover-sheet net change total.
• Optionally compare an independently supplied previous certified amount with the current application's previous-certificate field.
• Receive decimal-string results without binary floating-point rounding and with a stable input fingerprint.
• Distinguish evidence that was checked from evidence that was not supplied.

Each completed run returns one report. A report with discrepancies is successful work, not an application failure. Malformed input is rejected rather than silently skipped.

Who should use this Actor?

Construction controllers, project accountants, owner representatives and contractor-focused bookkeepers can use it as a repeatable arithmetic review step. It is especially relevant when numbers move between spreadsheets, billing portals and internal review tools.

Use it when you already have structured billing numbers. It does not read PDFs or images. If your process depends on extracting figures from scanned documents, verify that extraction separately before running this checker. A perfectly consistent report can still contain incorrect source data.

Real-world use cases

1. Check a monthly subcontractor application before assembling the owner's billing package.
2. Recheck a revised application and compare the findings with the previous run.
3. Add a review step after exporting schedule-of-values figures from a spreadsheet.
4. Give an accounting advisor a consistent exception report alongside the original project records.
5. Flag cover-sheet amounts that no longer agree with a revised continuation schedule.

These are intended workflows, not claims of customer adoption or guaranteed payment acceleration.

Quick start

Open the Input tab and use the prefilled example. It contains two illustrative schedule lines and a deliberately overstated current payment request. Run once, then open Complete arithmetic report in Output. The calculated current due is 17800.00; the example reports 18000.00, so the report flags a 200.00 difference.

Replace the example with your own figures only after confirming field meanings. Use decimal strings such as "1250.00", not JSON numbers, formatted currency or scientific notation. Use a single currency throughout the application. No exchange-rate conversion occurs.

Example input

{
  "currency": "USD",
  "cover": {
    "originalContract": "100000.00",
    "netChanges": "0.00",
    "contractToDate": "100000.00",
    "completedStored": "40000.00",
    "retainage": "4000.00",
    "earnedLessRetainage": "36000.00",
    "previousCertificates": "20000.00",
    "currentDue": "16000.00",
    "balanceToFinish": "64000.00"
  },
  "lines": [{
    "id": "MEP-01",
    "scheduled": "100000.00",
    "previousWork": "25000.00",
    "currentWork": "10000.00",
    "stored": "5000.00",
    "completedStored": "40000.00",
    "retainage": "4000.00",
    "balance": "60000.00"
  }],
  "approvedChanges": [],
  "previousCertified": "20000.00"
}

Input parameters

Field	Required	Meaning and limits
currency	Yes	Three uppercase letters; one currency per application.
cover	Yes	All nine amounts shown in the example; decimal strings.
lines	Yes	Between 1 and 5,000 schedule items with unique IDs.
approvedChanges	No	Up to 5,000 unique {id, amount} objects representing already-approved changes.
previousCertified	No	Independent cumulative certificate amount for comparison.

Every schedule line requires the eight fields shown above. previousWork means completed work carried from prior applications, currentWork means this period's completed work, and stored means materials presently stored. Do not include the same materials in both current work and stored materials. retainage is a reported monetary amount, not a percentage. Its contractual correctness is outside this tool's scope.

All monetary strings allow at most twelve integer digits and two decimal places. Negative amounts are accepted for legitimate adjustments; review their meaning yourself. Identifiers allow 1–120 characters without control characters. Unknown fields, duplicate identifiers, missing amounts and requests larger than two million UTF-8 bytes are rejected. Optional evidence omitted is marked not_supplied; an empty change list asserts zero approved changes.

Output and findings

The default dataset contains one complete report, also saved as OUTPUT in the run's key-value store. summary contains recalculated totals; findings contains discrepancy codes, input paths, reported amounts, expected amounts and differences. lines preserves IDs and zero-based input indexes with calculated values. coverage describes optional comparisons and exclusions. inputSha256 identifies the exact input JSON serialization; it does not authenticate underlying documents.

A representative finding for the prefilled example is:

{
  "code": "COVER_CURRENT_DUE_MISMATCH",
  "path": "cover.currentDue",
  "actual": "18000.00",
  "expected": "17800.00",
  "difference": "200.00"
}

Positive differences mean the reported amount exceeds the calculated comparator. They are not automatically overpayments or recoverable revenue. A zero-finding report means the implemented checks found no differences in the supplied numbers, not that the payment application is complete or certified.

How the checks work

Calculations use integer cents. Completed-and-stored value is previous work plus current work plus presently stored materials. Line balance is scheduled value minus that calculated total. Retainage is summed from reported line amounts; this tool does not infer percentages or apply statutory limits.

Cover comparisons use recalculated schedule totals, so an incorrect line subtotal does not hide a cover-sheet inconsistency. Earned less retainage is calculated completed-and-stored value minus reported line retainage. Current due subtracts reported previous certificates. Cover balance to finish includes retainage. Optional change and certificate comparisons use only the values you supply; no external database is consulted.

Pricing and cost examples

Launch pricing is $0.20 per completed application-check report, covering up to 5,000 schedule lines and 5,000 supplied change entries. One report is one billing event regardless of how many findings it contains. Malformed input is rejected before the report event. There is no per-discrepancy fee and no subscription purchased by this Actor.

One report costs $0.20 in Actor fees; 100 reports cost $20; 1,000 reports cost $200. Apify may also charge applicable platform usage under your plan. These are arithmetic examples, not forecasts of adoption or earnings. Set your run charge limit to at least $0.20. If output storage or charging fails, the run fails; inspect the run and dataset before retrying. A new manual run is a new chargeable report, even for identical input. Automatic retries and container restarts are disabled in the default configuration.

API integration and scheduling

Submit the tested JSON as the request body using a token stored in your environment:

const response = await fetch(
  'https://api.apify.com/v2/acts/wheresprada~construction-pay-application-check/runs?memory=128&timeout=30&maxTotalChargeUsd=0.20',
  { method: 'POST', headers: {
      Authorization: `Bearer ${process.env.APIFY_TOKEN}`,
      'Content-Type': 'application/json'
    }, body: JSON.stringify(input) }
);
if (!response.ok) throw new Error(`Apify returned ${response.status}`);
const {data: run} = await response.json();
console.log(run.id);

Poll the run until it finishes, then retrieve its default dataset. Never interpret a successful API submission as a completed report. An Apify task can save input for repeated use; update it with the current billing period before scheduling. A schedule with unchanged input merely repeats the same review and can incur repeated fees. Use webhooks for successful completion and handle failed runs separately. This Actor does not automatically connect to your accounting system.

Limits and accuracy

The fixed runtime is 128 MB with a 30-second timeout. There are no network fetches, proxies, OCR, AI calculations or external services. Two-decimal currencies only; currencies requiring different minor-unit precision are unsupported. Mixed-currency applications must be separated before use.

No checks establish physical progress, material ownership, lien-waiver validity, approval authenticity, contractual billing rights, retainage law or whether cash actually arrived. Previous certificates are not necessarily cash receipts. Retainage releases and unusual contract terms require professional interpretation. This is not a legal opinion, accounting audit or payment certification. AIA, G702 and G703 are marks of their respective owner; this independent tool is not affiliated with AIA and does not reproduce licensed forms.

Privacy and security

The implementation processes supplied input without contacting external websites. It does not need credentials to an ERP, bank or billing portal. Apify stores input, logs and output under its platform storage/access rules and your account settings. Do not submit bank details, personal identifiers or confidential records without appropriate authorization. Delete retained run storage when no longer required; this Actor does not promise automatic deletion or a particular retention period.

Troubleshooting and FAQ

Why did a number fail validation? Use quoted decimal strings without commas, symbols or more than two decimal places.

Why does a blank optional change list flag a discrepancy? An empty list means verified zero; omit the field if you do not have the evidence.

Can I upload a PDF? No. Transfer and verify the relevant numbers into the input structure first.

Why does line balance differ from cover balance? Cover balance includes retainage; line balance excludes it in this model.

Does a flagged retainage amount prove a violation? No. A range flag is a review prompt; contractual and legal requirements are not evaluated.

Will retries charge again? A new completed run is another report. Do not retry a successful report just because it contains findings.

Can this certify a payment? No. A qualified human must review the records and make that decision.

Support

Open an issue on this Actor's Apify Store page with the run ID, expected result, actual finding code and a minimal anonymized input. Never post tokens, bank details or confidential customer documents. Include field names and a small reproducible example so the calculation can be investigated without exposing your project records.