Toolfy Invoices feature review

This walkthrough shows exactly what the Invoices workspace does for a 1–10 person service team—what lives on the page, how payments route through Toolfy, and which APIs/policies keep everything reliable.

1. Builder basics

• Items & calculations: every invoice stores structured line items (name, qty, price) validated by Toolfy’s Zod schema. Totals are recomputed server-side so arithmetic mistakes never leave your org.
• Customers & jobs: link invoices to an existing customer or job record so job notes, photos, and invoice history stay in one timeline.
• Currencies & tax: choose an ISO 4217 currency and tax rate per invoice. Toolfy calculates subtotal, tax, and total, then locks them when you send.
• Notes & attachments: add scope notes, terms, or upload supporting files (survey photos, signed quotes) so the invoice is a full job packet.

2. Cash controls built in

| Control | Where it lives | Why it matters | | --- | --- | --- | | Deposits | Toggle in the invoice builder; set % or fixed amount | Charge 30–50% upfront before materials leave the van. | | Milestone billing | Duplicate the job per phase; attach invoices to statuses | Automate billing for survey/install/handover without copy-paste. | | Payment methods | Toolfy Payments settings (card, pay-by-bank, terminal) | Offer tap-to-pay on site or share links instantly. | | Auto fees | Optional “processing fee” line item template | Clearly show pass-through card fees when you need them. |

3. Sending, sharing, and reminders

• Send button: clicking Send triggers POST /api/invoices/:id/send, logging email delivery + status (sent, viewed, paid) right on the invoice.
• Payment link: generate a hosted checkout URL (POST /api/invoices/:id/payment-link) that drops the customer into Toolfy’s secure payment flow—no PDF edits.
• Reminder workflows: attach reminder sequences (SMS/email) by status. Example: Day 0 send, Day 3 reminder, Day 7 escalation. Workflows reference invoice variables (balance, due date) automatically.
• Review nudges: once an invoice is marked paid, trigger a “leave a review” message without touching another app.

4. Tracking & reporting

• Aging board: filter by Current, Overdue 1–15, Overdue 16–30+ and assign owners for follow-ups.
• Revenue widgets: dashboard tiles show invoices sent this week, overdue totals, and payment velocity.
• Exports: one-click CSV/QuickBooks exports carry invoice + payment data (customer, item, tax) for bookkeeping.
• Search & filters: query by customer, status, or text (q=) to find anything instantly.

5. Payments + reconciliation

• Instant payouts: enable same-day payouts for card/terminal transactions; Toolfy reconciles them back to the invoice to prevent double counting.
• Manual payments: log bank transfer/cash via the Payments tab; Toolfy enforces remaining_balance >= payment_amount so you can’t over-apply funds.
• Receipts & logs: each payment posts a receipt email, updates invoice history, and is visible on the customer timeline.

6. API & workflow coverage

| Action | Endpoint | Notes | | --- | --- | --- | | List invoices | GET /api/invoices | Supports limit, offset, status, customer_id, q. Scoped by x-org-id. | | Create invoice | POST /api/invoices | Requires Idempotency-Key for PAT/server calls; server recalculates totals. | | Update invoice | PATCH /api/invoices | Partial updates; immutable fields rejected. | | Send invoice | POST /api/invoices/:id/send | Emits structured logs + Sentry tags with x-agent. | | Payment link | POST /api/invoices/:id/payment-link | Returns { url, provider }; rejects already-paid invoices. |

All endpoints accept Supabase sessions or PATs with scopes (invoices:read, invoices:write, invoices:send, invoices:payment_link). Multitenancy is enforced via x-org-id, so automated workflows and MCP agents can only touch the org they’re scoped to.

7. Observability & safety nets

• Idempotency: create requests require Idempotency-Key, preventing duplicate invoices when workflows retry.
• Rate limits: write endpoints return 429 with X-RateLimit-* headers if you exceed per-user quotas—handy when you bulk import.
• Logging: every request logs route, org_id, user_id, and optional x-agent so you can trace who sent what.

8. Quick start checklist

1. Templates: build at least two invoice templates (callout vs project) with saved items and deposit defaults.
2. Payment rails: connect Toolfy Payments, enable pay-by-bank + tap-to-pay, and decide when to use instant payouts.
3. Reminders: set reminder sequences for sent, due soon, and overdue states.
4. Exports: schedule a weekly QuickBooks or CSV export so accounts see paid vs outstanding totals.
5. API tokens: create a PAT scoped to invoices:* if you want MCP/ChatGPT agents to create or send invoices on demand.

Have questions or want us to clone our sample templates into your workspace? Email support@toolfy.io and the success team will drop them in.