Inspiration

Fixed-fee software agencies get paid by milestone, and almost none of that process is automated. Someone reads the statement of work, argues about whether "the app should be fast" has been met, raises the invoice, chases it when it's late, and then works out what each subcontractor is owed. While the invoice sits unpaid, the next phase quietly slips and nobody updates the plan.

Every step in that loop is either reading a document or moving money. Claude is good at the first and PayPal is built for the second, so I wanted to see how much of the loop an agent could run if a person still approved every payment.

What it does

Milestone Pay takes a project from signed SOW to paid team:

  1. Reads the SOW. Claude extracts milestones, fees, dates and acceptance criteria, cites the page for each, and flags criteria nobody could verify, with a measurable rewrite to accept or reject.
  2. Verifies delivery. The team attaches evidence (pull requests, test reports, CI runs, client emails). Claude judges each criterion as met, not met or unclear, and explains why.
  3. Gets paid. Once every criterion is met and a person approves, the invoice goes out through PayPal Invoicing.
  4. Reacts to payment. The INVOICING.INVOICE.PAID webhook unlocks the next phase and queues subcontractor shares.
  5. Chases late payments. A daily sweep moves blocked phases back and drafts a friendly reminder, sent through PayPal's reminder API.
  6. Pays the team. Approved shares go out through PayPal Payouts after the client's money clears.

How I built it

The app is Next.js 16 (App Router, Server Actions), React 19, TypeScript and Tailwind CSS 4.

  • PayPal: OAuth 2.0, Invoicing v2 (create, send, remind, record payment), Payouts v1, and webhooks with signature verification.
  • Claude: structured outputs validated against Zod schemas, so the app never acts on a response it can't parse. PDFs go to Claude as document blocks, with no PDF parsing library.
  • Business rules: pure functions with no I/O, covered by Vitest. The agent workflows wrap them with the PayPal and Claude calls.
  • Storage: in memory by default, or Postgres when a database URL is set.

Every integration sits behind an interface with a real and a mock implementation, so npm install && npm run dev runs the full loop offline with no keys.

Two of the rules are small enough to state exactly. Money is stored in integer cents, and a subcontractor with a \(p\) percent split of a milestone worth \(A\) cents is owed

$$\text{share} = \operatorname{round}\left(\frac{A \cdot p}{100}\right)$$

When an invoice on a payment-gated milestone is \(o\) days overdue, the phase waiting on it must be delayed by a whole number of weeks:

$$d_{\text{required}} = 7 \left\lceil \frac{o}{7} \right\rceil$$

If the phase has already been moved \(d_{\text{current}}\) days, it and every later phase move by \(\Delta = d_{\text{required}} - d_{\text{current}}\), and only when \(\Delta > 0\). That makes the sweep safe to run as often as you like.

Challenges

  • Vague acceptance criteria. An agent can't verify "user-friendly". I had to define measurable (a number, a pass/fail outcome, or a named approval) and make the agent propose a rewrite instead of guessing.
  • Payments that arrive twice. A payment can reach the app from a webhook and from the app's own action, so applying one had to be idempotent: the second call changes nothing and queues no duplicate payouts.
  • Untrusted documents. SOWs and evidence come from third parties. They are passed to Claude as data, the prompts tell it never to follow instructions inside them, and the agent can only propose actions.
  • Serverless state. Each serverless instance has its own memory, so a webhook could land on an instance that had never seen the invoice. Optional Postgres storage fixed that.
  • PayPal's rules. Invoice numbers must be unique per merchant, which demo resets broke, and an invoice allows only two reminders a day.
  • Configuration mistakes. Pasted keys with stray quotes and database URLs with unsupported parameters failed silently, so the app now cleans them up and shows setup problems in the UI.

What I learned

  • An agent is most useful when it prepares and a person confirms. The approval queue became the centre of the product, not a safety add-on.
  • Keeping the business rules pure made the agent trustworthy: the model decides what the evidence shows, and plain tested code decides what happens to the money.
  • Mock-first integrations paid off. Being able to run everything offline made the demo reliable and the tests fast.
  • Webhooks are the hard part of a payments integration. Verifying signatures and handling repeats took more thought than calling the APIs.

What's next

Sign-in and multiple users, partial payments and change orders, and pulling evidence directly from GitHub and CI instead of pasting it in.

Built With

Share this project:

Updates

Submission history