# Explain Each User's Monthly Profit and Loss From Their Own QuickBooks

A finance app makes one agent per user, signed in to that user's QuickBooks, that explains last month's profit and loss in plain words for the app to show.

[Run this on Rush](https://cloud.getrush.ai/run/explain-monthly-profit-and-loss/quickbooks/). Opens the console with this prompt ready to send. Connect QuickBooks there first.

## What the agent does

This is for a software company whose product serves small-business owners: a cash-flow dashboard, a business banking app, or a tool for franchise operators. Its users keep their books in QuickBooks Online and want to know, in a few sentences, why last month looked the way it did. The company saves the agent once as a template, `POST /o/{org}/agents {"name": "Monthly P&L", "harness": "claude", "instructions": "…", "connections": ["quickbooks"]}`, after connecting a QuickBooks company of its own, because a template names connections its creator has. When a user turns the feature on, the backend makes that user's agent with `{"template": "<template id>", "name": "pnl-<your user id>"}` and stores the returned id against the user.

The user then connects their own books. The backend calls `POST /o/{org}/agents/{agent}/connections {"type": "app", "name": "quickbooks"}`, gets an `authorize_url`, and opens it in a popup for that signed-in user. They pick their company on Intuit's own page, which names Rush as the app asking, and the popup ends on Rush's "Connected" page. The company registers no app with Intuit and never holds a QuickBooks token: it holds an agent id, and the agent's runs reach that one user's company and no one else's.

Each month the agent reads the Profit and Loss report through the Accounting API, `/v3/company/<realmId>/reports/ProfitAndLoss`, with `start_date` and `end_date` covering the last three months and `summarize_column_by=Month`, then the same report for the same month a year earlier. It walks the report's rows for income, cost of goods sold, expenses and net income, and picks the accounts whose change against the month before is largest in money terms, not in percent, so a small account doubling does not crowd out rent going up.

It ends the turn with JSON the app can render: `headline`, one sentence; `net_income` for the month and the month before; `changes`, up to five accounts with both amounts and a one-line note on what moved; and `questions`, things the books cannot explain, such as an expense account that appeared for the first time or a month with no income recorded. It explains what the numbers say and stops there: no tax, lending or investment advice, and no edits to the books.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "<agent id>",
  "input": "Explain the profit and loss for October 2026. Read the ProfitAndLoss report for August to October 2026 with summarize_column_by=Month, and for October 2025. Compare October with September and with October 2025. Return only JSON: headline (one sentence), net_income {october, september}, changes (up to 5 accounts with the largest change in money against September, each with name, october, september and a one-line note), and questions (anything the books cannot explain, such as a new expense account or a month with no income). Describe the numbers only: give no tax, lending or investment advice, and change nothing in QuickBooks."
}
```

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 that JSON, in the session's `result` and in the `run.completed` webhook's `data.result`, which carries the result in full up to 16 KiB. The webhook also names the `execution_id`, which the backend saved against the user when it started the run, so it knows whose dashboard the summary belongs on. It can show `headline` at the top, `changes` as a short table, and `questions` as prompts for the owner or their bookkeeper.

What to check before showing it: that `net_income` matches the figure the app already computes from QuickBooks, if it computes one, and that the month is closed in the user's books. A summary of a month the bookkeeper is still categorizing will change, so many apps wait until the user marks the month done. The session's `accounts` field names the QuickBooks company the run acted for, and the transcript keeps each report call, so a user who asks where a number came from gets a real answer.

## Run it on every month end, per user

On the fifth of each month, the app's scheduler loops over users with the feature on and sends one `POST /o/{org}/sessions` per agent, each with the month in `input` and a `request_id` that is a UUID v5 of the user's id and the month, so a scheduler that retries does not start a second run for the same user. Runs past the key's concurrent limit are created `queued` and start as slots free, so the loop needs no back-off of its own.

A user who never finished connecting is refused `422 CONNECTION_NOT_READY` before a sandbox starts. A user who revoked Rush's access at Intuit shows `needs_reauth` on `GET /o/{org}/agents/{agent}/connections`. The app checks for either, skips that user this month, and asks them to reconnect through a fresh `authorize_url` the next time they open the dashboard.

## Why run it on Rush?

The hard part of this feature is not the summary, it is holding every user's QuickBooks sign-in safely and running one job per user without one user's data leaking into another's. On Rush each user's account belongs to their own agent: an agent's run never sees the company's accounts or another agent's, Rush refreshes the tokens, and the product team stores only agent ids.

Each run has its own computer, its own record, and its own cost. `GET /o/{org}/sessions?agent=<agent id>` lists one user's runs with their `total_cost_usd`, so the company can see what the feature costs per user and bill it back if it wants to. When a user deletes their account in the app, `DELETE /o/{org}/agents/{agent}` removes their agent and disconnects their QuickBooks.

## Frequently asked questions

### Do we need our own Intuit developer app?

No. Each user signs in on Intuit's page to Rush's app, and Rush stores and refreshes the token under that user's agent. You keep the map from your user to the agent id and nothing else.

### Can one agent read two of a user's QuickBooks companies?

An agent holds one account per app, and connecting another replaces the first. A user with two companies gets two agents from the same template, one per company.

### Does the agent give financial advice?

The prompt and the template's instructions limit it to describing what the report shows and listing what it cannot explain. Advice on tax, borrowing or investing is out of scope and stays with the user's accountant.

### What happens when we change the template's instructions?

Every agent made from it runs the template's current revision, so a `PATCH` on the template reaches each user's next run. Agents' own fields are only their name and description.

## More QuickBooks jobs

- [Find Last Month's Uncategorized Expenses in QuickBooks Before the Close](https://getrush.ai/run/find-uncategorized-expenses/quickbooks/)
- [Follow Up on Overdue QuickBooks Invoices Every Week](https://getrush.ai/run/follow-up-on-overdue-invoices/quickbooks/)
- [Which Supplier Bills Are Due This Week, and for Which Job? A Construction App Lists Each Contractor's QuickBooks Bills](https://getrush.ai/run/list-bills-due-this-week-by-job/quickbooks/)

## More jobs like this: Run an agent per customer task

- [Read Supplier Invoice PDFs From Each Customer's OneDrive Into Draft Bills](https://getrush.ai/run/extract-supplier-invoices/onedrive/)
- [Find Personal-Training Clients With No Next Session Booked in Each Trainer's Google Calendar](https://getrush.ai/run/find-clients-without-a-next-session/google-calendar/)
- [Which Donors Gave Last Year but Not This Year? A Fundraising App's Monthly Airtable Check for Each Nonprofit](https://getrush.ai/run/find-lapsed-donors/airtable/)

## Keep reading

- [Connect QuickBooks to Rush once, then name it on any run](https://getrush.ai/integrations/quickbooks/)
- [Start your first run from the developer API quickstart](https://getrush.ai/docs/quickstart/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
