All jobs

Which Supplier Bills Are Due This Week, and for Which Job? A Construction App Lists Each Contractor's QuickBooks Bills

A construction-management app makes one agent per contractor, signed into its QuickBooks, that lists each week's unpaid bills due by job and supplier.

Run this on RushOpens the console with this prompt ready to send. Connect QuickBooks there first.

What the agent does

This is for a company that sells job-management software to specialty contractors: electricians, HVAC installers, concrete and framing crews. Its users schedule crews and track job budgets in the app, and keep their books in QuickBooks Online, where every supplier invoice for wire, ductwork or rebar is entered as a bill. On Monday morning the office manager decides which bills to pay this week, and the question is never only what is due: it is which job each bill belongs to, whether that job has been paid by its own customer, and which supplier will hold the next delivery if a bill slips. The software company saves one agent as a template that names QuickBooks and makes one agent from it per contractor.

The company connects a QuickBooks company of its own first, because a template names connections its creator has, then saves the template with POST /o/{org}/agents {"name": "Bills due", "harness": "claude", "instructions": "…", "connections": ["quickbooks"]}. When a contractor turns the feature on, the backend makes the contractor's agent with {"template": "<template id>", "name": "bills-<contractor id>"}, calls POST /o/{org}/agents/{agent}/connections {"type": "app", "name": "quickbooks"} and opens the authorize_url for the office manager, who picks the company on Intuit's own page. Rush's QuickBooks sign-in asks for the accounting scope, which reads and records; the template's instructions keep this agent to reading.

On a run the agent sends a query to the QuickBooks Online Accounting API's query endpoint, SELECT * FROM Bill WHERE DueDate <= '<end of the week>', paging with STARTPOSITION and MAXRESULTS. Intuit's schema describes Balance as the unpaid amount of the bill, zero when paid in full, and marks it filterable only in QuickBooks Desktop, so the agent keeps bills whose Balance is above zero itself instead of asking QuickBooks to filter on it. For each bill it reads VendorRef, DocNumber, TxnDate, DueDate, TotalAmt and Balance, and from each line the CustomerRef (the customer or job the expense is for), and ProjectRef where the company uses QuickBooks projects.

It groups the bills by job, using the job names the contractor's app sends in the prompt to match QuickBooks customers and projects, and within each job lists supplier, bill number, due date and balance. Bills already past due go first; bills with no job on any line go in their own section, because an unassigned bill is usually a data-entry gap the office manager wants to fix before paying. It records no payment, edits no bill and writes nothing to QuickBooks. The office manager approves the week's payments in QuickBooks or the bank, as they do now.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "<agent id>",
  "input": "List the supplier bills due by 2026-11-21 for this contractor. Query the QuickBooks query endpoint with SELECT * FROM Bill WHERE DueDate <= '2026-11-21', paging with STARTPOSITION and MAXRESULTS until no more come back. Keep bills with Balance > 0. For each, read VendorRef name, DocNumber, TxnDate, DueDate, TotalAmt, Balance, and each line's CustomerRef and the bill's ProjectRef if present. Active jobs in our app (job name: QuickBooks customer or project name): Riverside Clinic fit-out: Riverside Medical Group; Oak St duplex: Oak Street Duplex; Lakeview school HVAC: Lakeview USD. Return only JSON: {overdue: [bill], by_job: [{job, total_balance, bills: [bill]}], no_job: [bill], total_balance}, where bill is {vendor, doc_number, txn_date, due_date, total, balance, days_overdue, quickbooks_customer_or_project}. Sort bills in each list by due date. Do not create, update or delete anything in QuickBooks, and do not record any payment."
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The answer is JSON in the session's result and in the run.completed webhook. The app shows it on the office manager's Monday screen beside each job's budget and its own customer payments, so the manager sees in one place that the Oak St duplex has three supplier bills due and an unpaid progress invoice of its own.

What the office manager checks before paying: that a bill grouped under a job really belongs to it (a line coded to the wrong customer moves cost onto the wrong job), any bill in the no-job section, and the supplier terms they have agreed outside QuickBooks, which the bill's due date may not reflect. The list says what is owed and when; which bills to pay first is the office manager's call.

Run it on every Monday morning

The app's scheduler sends one POST /o/{org}/sessions per contractor at 6 a.m. Monday in the contractor's time zone, with that contractor's agent id as agent, the coming Friday's date and the active job list in input, and a request_id that is a UUID v5 of the contractor id and the week. A retried job starts no second run, and every contractor's run starts at once.

An office manager can also press Refresh after entering a batch of bills midweek, which starts the same request with the same Friday.

The use case this job follows, with its automation and trigger: Run an agent per customer task.

Why run it on Rush?

Each contractor signs in to Intuit on Intuit's page and that sign-in belongs to its own agent: the software company registers no app with Intuit, holds no QuickBooks token, and one contractor's run reaches that contractor's company and no other. A session lists the QuickBooks company it read by its realm id in accounts, so the company can show a contractor exactly which runs touched their books.

One template serves every contractor, so adding a column, such as each job's retainage, is one PATCH to the template that reaches every next run. Each run has its own computer and a record of every query it sent and what its model calls cost, and GET /o/{org}/sessions?agent=<agent id> totals a contractor's runs by total_cost_usd.

Frequently asked questions

Can the agent pay bills or mark them paid?

No. Rush's QuickBooks sign-in carries the accounting scope, which could record a bill payment, so the template's instructions and each prompt forbid every write. The transcript lists every request the agent sent to QuickBooks, which shows it only queried.

What if the contractor does not code bills to jobs?

Then every bill lands in the no-job section and the list is still a due-date view grouped by supplier. Coding each bill line to a customer or project in QuickBooks, which Intuit's schema supports with CustomerRef on the line, is what makes the job grouping work.

Does this give accounting or cash-flow advice?

No. It lists what QuickBooks says is owed, when and for which job, and leaves the decision about what to pay to the office manager and their accountant.

Does the contractor need a Rush account?

No. The office manager signs in to QuickBooks from the job-management app, and the agents, their runs and their cost belong to the person who created the software company's API key.

More QuickBooks jobs

More jobs like this: Run an agent per customer task

Keep reading