All jobs

How Does Bookkeeping Software Turn Each Seller's PayPal Month Into Lines for the Books?

A bookkeeping app for small online sellers makes one agent per seller that reads their PayPal month and drafts the sales, fees, refunds and transfers to book.

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

What the agent does

This is for a software company that keeps the books for very small online sellers: people who sell prints, candles or vintage clothing through their own site and a marketplace and take payment through PayPal. Every month the app needs the same few figures from each seller's PayPal: gross sales, PayPal's fees, refunds, chargebacks, money held for disputes, and the withdrawals to the bank, which have to match the deposits on the bank statement. Sellers are asked to export a CSV and upload it, and many forget. The company replaces the upload with an agent per seller that reads PayPal directly.

The company saves the agent once as a template with POST /o/{org}/agents, naming the PayPal server in connections (it connects a PayPal business account of its own first) and instructions that keep it to reading. When a seller turns on PayPal sync, the backend makes their agent with {"template": "<template id>", "name": "paypal-<seller id>"}, calls POST /o/{org}/agents/{agent}/connections {"type": "mcp", "name": "paypal"}, and opens the authorize_url in a popup for that seller, who logs in and consents on PayPal's page. The company stores only the agent id against the seller.

A run calls PayPal's List Transactions tool (list_transactions in PayPal's agent toolkit), which reads PayPal's Transaction Search API with a start_date and end_date at most 31 days apart, so one calendar month fits in one call, paged with page and a page_size of up to 500. The toolkit lists successful transactions unless transaction_status says otherwise, so the run asks again for P (pending) and V (reversed). Each transaction carries its transaction_event_code, transaction_amount, fee_amount, transaction_status, transaction_initiation_date and, when the sale had one, invoice_id.

The agent groups by event code as PayPal's code list defines them: T0006 Express Checkout and T0007 standard web checkout payments are sales, T1107 is a payment refund, T1201 a chargeback, T1110 and T1111 a hold for a dispute and its release, and T0400 and T0403 withdrawals to a bank. Any code the prompt does not name goes to a list of its own instead of a guessed account. It writes the month's totals per currency, one line per withdrawal with its date and amount for matching against the bank feed, and draft journal lines in the chart of accounts given in input. It refunds, invoices and accepts nothing.

Start it with one API call

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

{
  "agent": "<agent id>",
  "input": "Summarize my PayPal activity for October 2026 for my books. Call list_transactions with start_date 2026-10-01T00:00:00-07:00 and end_date 2026-10-31T23:59:59-07:00, page_size 500, every page; then the same with transaction_status P and with transaction_status V. For each transaction keep transaction_id, transaction_event_code, transaction_initiation_date, transaction_amount, fee_amount, transaction_status, invoice_id. Group by event code: T0006 and T0007 sales; T1107 refunds; T1201 chargebacks; T1110 and T1111 dispute holds and releases; T0400 and T0403 bank withdrawals; any other code under Other with the code. Write paypal-2026-10.json: totals per currency for gross sales, fees, refunds, chargebacks, net held for disputes and withdrawals; each withdrawal with its date and amount; pending and reversed transactions listed apart; Other listed in full. Then draft journal lines with these accounts: 4000 Sales, 6150 Merchant fees, 4090 Refunds, 6160 Chargebacks, 1050 PayPal clearing, 1000 Bank. Do not call create_refund, accept_dispute_claim, create_invoice, send_invoice or any tool that creates, sends or changes anything."
}
  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 session returns paypal-2026-10.json as an artifact. The app's webhook handler reads it, puts the draft journal lines in the seller's review queue beside the month's bank deposits, and marks each withdrawal that matches a deposit by date and amount.

What the seller or their bookkeeper checks before posting: every line under Other, which the agent did not book; pending transactions, which may settle next month; and any withdrawal with no matching deposit. The app posts nothing until a person approves the lines, and the grouping follows PayPal's codes, not a view of how the seller should account for them.

Run it on every the 2nd of each month, per seller

The app's scheduler sends one POST /o/{org}/sessions per seller with sync on, at 06:00 on the 2nd in the seller's time zone, with that seller's agent id, last month's dates and their chart of accounts in input, and a request_id that is a UUID v5 of the seller id and the month. PayPal's reference says an executed transaction can take up to three hours to appear in the list, so a run on the 2nd reads a complete month. Runs past the key's max_concurrent wait as queued and start as slots free.

A seller who connects PayPal partway through the year can ask for earlier months from the app. It sends one request per month, since each search covers at most 31 days, and PayPal's reference says the search reaches back three years.

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

Why run it on Rush?

The seller logs in to PayPal on PayPal's page and Rush keeps the grant under that seller's agent, so the company stores no PayPal credentials and no seller's run can read another seller's account. When a seller disconnects PayPal in the app, the agent's next run is refused until they connect again.

Each month is a session with its own computer, a record of every PayPal call and its result, and its model cost, which the company totals per seller with GET /o/{org}/sessions?agent=<agent id>. When a seller asks why a fee was booked where it was, support opens that month's transcript instead of re-running a script against a stored token.

Frequently asked questions

Why not ask sellers for PayPal's CSV export?

The export holds the same transactions, but someone has to download it every month and upload it, and a seller who forgets leaves the month open. The agent reads the Transaction Search data on a schedule, and the seller's only step is logging in to PayPal once.

Can the agent issue a refund or accept a dispute?

The PayPal server has tools for both, create_refund and accept_dispute_claim, which is why the template's instructions and every prompt name them as forbidden. The transcript lists each tool a run called, so the company can confirm no run used them.

What about sales in more than one currency?

Every amount comes with its currency, and the totals are written per currency. Any transaction whose event code the prompt does not name goes under Other for a person to book.

Does the agent decide how each line is booked?

It maps PayPal's event codes to the accounts the seller's chart names in input and leaves everything else for a person. How a sale, a fee or a chargeback belongs in the books is the seller's or their bookkeeper's decision, and the app posts nothing they have not approved.

More PayPal jobs

More jobs like this: Run an agent per customer task

Keep reading