From request to cash, on autopilot.
Quotely is an AI quote-to-cash app for small B2B service businesses: equipment rental, catering, event agencies, AV installers. A customer email becomes a priced quote, the quote becomes a PayPal deposit invoice, the finished job becomes a balance invoice, and a reminder agent chases what is late, until the money is in.
Built for the PayPal AI Hackathon on the PayPal × AG Grid boilerplate.
- A request arrives. Paste a customer email into the inbox.
- AI drafts the quote. OpenAI reads the request, extracts the customer, job dates, place and line items, and matches each item to the company price list. It never invents a price: anything not on the price list is flagged Needs a price and blocks approval.
- The operator reviews. Every line is editable inline; the source email sits next to the quote with each extracted phrase highlighted and linked to its line.
- Approve → deposit invoice. Quotely creates and sends a PayPal invoice for the deposit (30% by default) through the PayPal Invoicing API.
- Payment is detected. A PayPal webhook (signature-verified) and a 30-second reconciliation both confirm payments with PayPal before anything changes. The quote moves to Deposit paid and a "Payment received" toast appears.
- Job done → balance invoice. One click sends the remaining balance as a second PayPal invoice. One invoice per stage, never duplicates.
- The nudge agent chases. It drafts friendly reminders with AI for deposits about to fall due and balances past due, schedules them for 09:00 Milan time, and stops as soon as PayPal confirms payment.
- The dashboard shows money in motion. An AG Studio canvas with KPIs, weekly cash movement, a money-flow funnel, a "who owes what" scoreboard, the agent's activity and a receivables ledger, all editable in Studio's Edit mode.
| Inbox | Quote builder | Quote detail |
|---|---|---|
![]() |
![]() |
![]() |
| Tool | How Quotely uses it |
|---|---|
| PayPal Invoicing API v2 (sandbox) | Create draft invoices, send them, read their status, search by invoice number (to recover safely after a failure), cancel. lib/paypal.ts |
| PayPal Webhooks | INVOICING.INVOICE.PAID and INVOICING.INVOICE.CANCELLED at POST /api/paypal/webhook, verified with POST /v1/notifications/verify-webhook-signature, then re-confirmed by reading the invoice. |
| PayPal OAuth 2.0 | Client-credentials token, cached until just before expiry. The Verify connection button in Settings mints one. |
AG Studio (ag-studio, ag-studio-react 3.0) |
The dashboard: AgStudioProvider, a saved report as initial state, native KPI / line / grid / donut widgets, three custom React widgets registered with createWidgets, the dark theme via studioTheme.withParams, real Edit mode and the AI Assistant. |
| OpenAI Responses API | Quote extraction with strict structured JSON output, and reminder drafting. One model, gpt-5.6-luna, set in lib/ai/index.ts; prompts in lib/ai/prompts.ts. The key never reaches the browser. |
| Next.js 16 (App Router) | Server components, server actions, route handlers, after() for the agent run, route-level loading and error states. |
| Prisma + PostgreSQL | One schema for local development and Render (integer cents, enums, no native types). |
| Tailwind CSS 4 | The "Obsidian × Lime" dark theme from docs/design-system.md, as CSS tokens. |
flowchart LR
subgraph Browser
UI[Inbox · Builder · Quote detail · Settings]
Studio[AG Studio dashboard]
end
subgraph Next.js server
SA[Server actions]
WH["/api/paypal/webhook"]
RC["/api/paypal/reconcile"]
NG["/api/agent/nudge"]
AIP["/api/ai/responses (Studio AI proxy)"]
Billing[lib/billing.ts<br/>approve · issueInvoice · markInvoicePaid]
Agent[lib/agent/nudge.ts]
Extract[lib/ai/extract.ts]
DB[(Prisma · PostgreSQL)]
end
PayPal[(PayPal sandbox)]
OpenAI[(OpenAI)]
UI --> SA
Studio --> SA
Studio --> AIP --> OpenAI
SA --> Extract --> OpenAI
SA --> Billing
SA -- every 30 s --> Billing
SA -- every 60 s, after response --> Agent
WH --> Billing
RC --> Billing
NG --> Agent --> OpenAI
Agent --> Billing
Billing <--> PayPal
PayPal -- webhook --> WH
Billing --> DB
Agent --> DB
Extract --> DB
Money rules worth knowing
- Money is stored as integer cents, EUR only.
- Prices come only from the price list or the operator. The model never sees or returns prices; its SKUs are checked against the price list and its quoted phrases must appear verbatim in the email.
- One invoice per stage: the invoice row is reserved before PayPal is called (unique on quote + stage), so double clicks and retries find it instead of creating another. A retry first searches PayPal by Quotely's unique invoice number (e.g.
Q-1042-D-QXT9). - Paid means PayPal says
PAID, in EUR, for the full amount, on a fresh read of the invoice. Webhook and polling both end in the same idempotentmarkInvoicePaid(). A webhook body alone never marks anything paid. - Every state change is written to an activity log with its actor: operator, PayPal, agent or system.
- Reminders are drafted and logged, never emailed (v1). PayPal itself sends the sandbox invoice emails.
Quote states: draft → approved → deposit_due → deposit_paid (= in_progress) → balance_due → paid. Overdue is a flag computed from due dates, not a state.
app/(app)/ Inbox, quote builder, quote detail, quotes list, settings, dashboard
app/(app)/dashboard/ AG Studio: data sources, report state, theme, custom widgets
app/api/paypal/ Webhook and reconciliation endpoints
app/api/agent/nudge/ Nudge agent endpoint
app/debug/ The boilerplate's original pages (raw PayPal endpoints, demo dashboard)
lib/paypal.ts Every PayPal call (sandbox host fixed)
lib/billing.ts Approval, invoices, payments, reconciliation
lib/agent/ The nudge agent and reminder text
lib/ai/ Model config, prompts, structured-output calls, extraction
lib/drafting.ts Requests and draft quotes
lib/cashflow.ts The dashboard's data
prisma/ Schema and seed (Northstar Rentals, Milan)
docs/ Design system and PayPal sandbox testing guide
Requires Node.js 20.9+, a PostgreSQL database (see Database) and a PayPal sandbox REST app (developer.paypal.com).
npm install # also generates the Prisma client (postinstall)
cp env.example .env.local # then fill in the values below, DATABASE_URL included
npm run db:reset # create the tables and load the demo data
npm run devOpen http://localhost:3000 (it lands on the dashboard). .env.local is git-ignored. The Prisma CLI reads it too (through prisma.config.ts), so npm run db:* and the app always use the same database.
Quotely runs on PostgreSQL everywhere. For local development, pick one:
A local PostgreSQL in Docker (recommended; your demo data stays separate from production):
docker run --name quotely-db -d -p 5432:5432 \
-e POSTGRES_USER=quotely -e POSTGRES_PASSWORD=quotely -e POSTGRES_DB=quotely \
-v quotely-db:/var/lib/postgresql/data postgres:16DATABASE_URL=postgresql://quotely:quotely@localhost:5432/quotely
Stop and start it later with docker stop quotely-db / docker start quotely-db; the data lives in the quotely-db volume.
Or the Render database: in the Render dashboard, open the PostgreSQL instance → Connect → copy the External Database URL into DATABASE_URL (append ?sslmode=require if it has no query string). Local runs then read and write the deployed data, and npm run db:seed / db:reset replace everything in it.
| Variable | Required | What it is |
|---|---|---|
PAYPAL_CLIENT_ID, PAYPAL_SECRET |
yes | Sandbox REST app credentials. |
PAYPAL_WEBHOOK_ID |
for webhooks | The webhook's ID from the PayPal dashboard. Without it, webhook events are accepted unverified in development only; payments are still detected by polling. |
QUOTELY_CRON_SECRET |
in production | Shared secret for x-quotely-cron on /api/paypal/reconcile and /api/agent/nudge. Open in development when unset. |
AG_STUDIO_OPENAI_API_KEY (or OPENAI_API_KEY) |
for AI | OpenAI key for quote drafting, reminders and the Studio assistant. Without it, quotes can be created manually. |
OPENAI_MODELS |
no | Models the Studio assistant may offer, comma-separated (first is the default). |
AG_STUDIO |
no | AG Studio licence key; without it Studio shows a trial watermark. |
DATABASE_URL |
yes | PostgreSQL connection string: local Docker, or Render's External (local) / Internal (on Render) Database URL. |
| Command | Does |
|---|---|
npm run dev / build / start / lint |
The usual Next.js scripts. |
npm run db:push |
Create or update the tables to match prisma/schema.prisma. |
npm run db:seed |
Replace all data with the demo data (dates are relative to today). |
npm run db:reset |
Drop and recreate the tables, then seed. |
All three use DATABASE_URL. To target another database once, prefix the command: DATABASE_URL="postgresql://…" npm run db:seed (a variable already set in the shell wins over .env.local).
The demo company is Northstar Rentals (Milan) with customers from an events agency, catering companies and an AV installer: 11 price-list items, 3 new requests (including Studio Marconi: 4 × 65" displays, 2 mic kits, delivery and setup, €2,800.00, deposit €840.00), and 6 quotes across every stage including an overdue balance and a fully paid job. Seeded quotes with invoices are marked Demo data and never talk to PayPal; only quotes created in the app do.
- Create a PostgreSQL instance, then a Web Service from this repository (Node).
- Environment:
DATABASE_URL= the database's Internal Database URL, plusPAYPAL_CLIENT_ID,PAYPAL_SECRET,PAYPAL_WEBHOOK_ID,QUOTELY_CRON_SECRET,AG_STUDIO_OPENAI_API_KEY,OPENAI_MODELS,AG_STUDIO. - Build command:
npm install && npx prisma generate && npx prisma db push && npm run build(prisma generatealso runs onpostinstall;db pushcreates or updates the tables). Start command:npm start. - Load the demo data once, from your machine:
DATABASE_URL="<External Database URL>" npm run db:seed. - Register the PayPal webhook at
https://<your-service>.onrender.com/api/paypal/webhook(see the testing guide).
In production, webhook events without a valid signature are rejected (so PAYPAL_WEBHOOK_ID is required for webhooks; polling works regardless), and the scheduler routes require QUOTELY_CRON_SECRET. A Render Cron Job can call them with curl -X POST … -H "x-quotely-cron: …".
docs/paypal-sandbox-testing.md walks through it step by step: draft the Studio Marconi quote, approve it, pay the deposit invoice as the sandbox buyer, watch it arrive, complete the job and pay the balance. It also covers registering the webhook through ngrok (https://<your-ngrok-host>/api/paypal/webhook, events Invoicing invoice paid and Invoicing invoice cancelled).
The scheduler endpoints can be called from any cron:
curl -X POST http://localhost:3000/api/paypal/reconcile -H "x-quotely-cron: $QUOTELY_CRON_SECRET"
curl -X POST http://localhost:3000/api/agent/nudge -H "x-quotely-cron: $QUOTELY_CRON_SECRET"The dashboard follows docs/design-system.md. Where AG Studio 3.0.0 has no matching setting, the closest documented option is used:
| Design doc | In Studio 3.0.0 | Used instead |
|---|---|---|
chromeBackgroundColor |
Exists but is excluded from Studio's theme API | Shell colour on the panel containers (studioPanelContainerBackgroundColor). |
| Grid background | No gridBackgroundColor |
gridDataBackgroundColor and gridOddRowBackgroundColor. |
| 16px widget gaps, 18px widget padding | No gap parameter; inner padding fixed | layout.widgetPadding: 8 (8px around each widget = 16px gaps); about 8px inside. |
| Font weights 600 / 650 | Widget typography is normal or bold |
bold. |
| Dashed "expected" line | No per-series line style | Three solid series: deposits received (teal), balances received (lime), expected (blue). |
| Palette order 1–6 | Colours are assigned in palette order | Teal and lime first, so deposits are always teal and balances lime on both the line and the donut. |
| Y-axis tick interval | The format parser drops unknown axis keys | A pre-configured copy of the built-in line chart (quotely-cash-movement, from Studio's _ALL_WIDGET_DEFS) whose widget options set the axes, including interval.minSpacing. Line charts created in Edit mode keep Studio's defaults. If that export disappears in a later Studio version, the report falls back to the plain line chart. |
| Overdue rows tinted | No row-style hook in the grid widget | The Stage cell renderer adds a marker; a CSS :has() rule tints the row. |
| "Sum" labels | Aggregated fields show "(sum)" | Named measures (expressions), e.g. Deposits received. |
| Custom widget data | Studio's context is read once |
Custom widgets read live data from a small store the page updates. |
Edit mode: Customize dashboard switches Studio to Edit mode with the AI Assistant folded away so the canvas fits at 1440px; Done customizing keeps the layout in this browser; Reset layout restores the built-in one. Widgets move by dropping them on free canvas space. The built-in layout sizes the list widgets to the data they hold.
- Single operator, no login. Server actions and routes validate every input, but do not deploy publicly with real credentials without adding authentication.
- PayPal sandbox only; the API host is hard-coded.
- No email is sent by Quotely. Reminders are logged and shown in the app.
- Prices in EUR only, no VAT handling.
The boilerplate's original pages are kept under /debug: raw PayPal endpoints in AG Grid (/products, /plans, /invoices, /transactions, /balances) and its demo AG Studio dashboard (/debug/dashboard).



