Invoice Chase

# Invoice Chase

## Quick start

Pull the AR aging report, score each customer by payment history, draft a tone-matched reminder for each overdue invoice, and present them to the owner. Nothing sends until the owner says so.

``` User: "who owes me money" → Pull AR aging from the ledger → Cross-reference recent payments (PayPal 7-day window; other processors and the storefront 14 days; Airwallex paid status) → Score each customer: good-payer / occasionally-late / repeat-late → Draft tone-matched reminders → Show summary table + drafts. Wait for "send these." ```

## Setup (first run only)

Ask the owner one question before running for the first time:

1. **Mail connector**: "Do you use Gmail or Microsoft 365 for drafts?" — store the answer; use it for all non-PayPal draft queuing. If only one mail connector is connected, use it and skip the question. Either way, confirm the mailbox is the owner's before queuing a draft in it (`../../shared/tenant-scope.md`).

Do not ask again on subsequent runs. Stripe is not a setup question: when it is connected, its overdue invoices are pulled every run (`reference/v2_sources.md`).

## Workflow

1. **Pull overdue receivables.** Query the ledger's AR aging — MYOB, NetSuite, QuickBooks, Xero, or Zoho Books, whichever is connected (`../../shared/connector-neutrality.md`) — for all invoices more than 1 day past due. If Stripe is connected, also pull Stripe overdue invoices. If Airwallex is connected, also pull its unpaid invoices: `list_billing_invoices` with `status: FINALIZED` and `payment_status: UNPAID` (a voided invoice still reports UNPAID, so the status filter is not optional), then match each to the ledger by the ledger invoice number in its `metadata` — never by Airwallex's own `number`, which it assigns itself and which matches nothing in the books; with no `metadata`, match on customer plus amount plus due date. Amounts carry the business's currency code (`../../shared/currency-and-locale.md`).

2. **Cross-reference payment history.** For each overdue customer, query PayPal for settled transactions using these parameters: - `transaction_status: S` (settled only — filters out pending and denied transactions that inflate result size and increase rate-limit risk) - Date window: **last 7 days** ending today (not 14 or 30 — wider windows are the primary cause of PayPal 429 rate limit errors)

**If PayPal returns a 429 rate limit error:** - Retry once immediately with a **3-day window** instead. - If the retry also returns 429, skip the PayPal cross-reference entirely for this run. Flag all customers in the batch as "PayPal unavailable — verify manually" in the summary table. Proceed to scoring using QuickBooks history only. Do not silently drop the caveat.

If a customer shows a settled payment within the query window, flag as "possibly paid — verify" and exclude from the draft queue.

Run the same recent-payment check against every other connected processor or storefront — Stripe charges, Square payments, Shopify orders (`list-orders` by customer, paid status) — before drafting, over the **last 14 days**. PayPal alone is capped at 7 because of its rate limit; the 14-day rule in the approval gates is the standard, and the PayPal cap is the one exception, said in the output when it applies. The sources and the dedupe rule are in `reference/v2_sources.md`. A settlement in any of them is a "possibly paid — verify" flag, not a reminder.

**Match on email where both sides have one.** Processors and storefronts key customers by email; ledgers key by name. Use the ledger's customer email when it exposes one (QuickBooks, Xero, Zoho Books, NetSuite do; MYOB does not). Where only a name is available, a name-only match is uncertain: keep the customer in the draft queue and mark the row "name match only — verify" rather than treating it as paid or as unmatched.

If Airwallex is connected, its side of the check is the invoice itself: an Airwallex invoice whose `payment_status` is `PAID` while the ledger still shows the balance open is "possibly paid — verify" too. No date window and no rate-limit retry are needed; it is one list call.

3. **Score each customer.** Read [reference/tone-matching.md](reference/tone-matching.md) for scoring logic. Result: `good-payer`, `occasionally-late`, or `repeat-late`.

4. **Draft reminder emails.** One email per customer — consolidate multiple overdue invoices into one email. Match tone to score. See [reference/examples/gentle-reminder.md](reference/examples/gentle-reminder.md) and [reference/examples/firm-reminder.md](reference/examples/firm-reminder.md).

5. **Present drafts to owner.** Show a summary table first:

| Customer | Amount Due | Days Late | Tone | Send via | |---|---|---|---|---| | Acme Corp | USD 1,200 | 18 days | Gentle | PayPal | | Smith LLC | USD 450 | 47 days | Firm | Gmail draft | | Pearl St Bistro | USD 467 | 91 days | Firm | Gmail draft + Airwallex pay link |

Then show each draft