back
loading skill details...
Generate, manage, and track professional invoices with client onboarding, customizable payment terms, recurring billing, automated overdue reminders, and fin...
---
name: afrexai-invoice-engine
description: Generate, manage, and track professional invoices with payment terms, recurring billing, overdue automation, and financial reporting. Use when creating invoices, tracking payments, managing clients, or reviewing revenue.
---
# Invoice Engine — Complete Invoicing & Accounts Receivable
A zero-dependency agent skill for end-to-end invoicing — from quote to payment to reporting.
## Quick Start
When the user says "create an invoice" or "bill [client]":
1. Check if client exists in memory (see Client Registry below)
2. If new client → run Client Onboarding
3. Generate invoice using the Invoice Builder
4. Present for review → finalize
5. Track in the Invoice Ledger
---
## 1. Client Registry
Maintain a YAML client database in your workspace:
```yaml
# clients.yaml
clients:
- id: "CLI-001"
name: "Acme Corp"
contact: "Jane Smith"
email: "jane@acme.com"
address:
line1: "123 Business Ave"
line2: "Suite 400"
city: "New York"
state: "NY"
zip: "10001"
country: "US"
tax_id: "US-EIN-12-3456789"
payment_terms: "net-30" # net-15, net-30, net-45, net-60, due-on-receipt, custom
preferred_currency: "USD"
default_tax_rate: 0 # 0 for B2B cross-border, local rate for domestic
notes: "PO required for invoices > $5,000"
created: "2026-01-15"
lifetime_revenue: 12500.00
invoices_sent: 3
invoices_paid: 2
avg_days_to_pay: 22
```
### Client Onboarding Checklist
When adding a new client, collect:
- [ ] Legal entity name (exactly as on their records)
- [ ] Billing contact name + email
- [ ] Billing address (full, with country)
- [ ] Tax ID / VAT number (if applicable)
- [ ] Preferred payment terms
- [ ] Currency preference
- [ ] Any PO or approval requirements
- [ ] Tax-exempt? (if so, get certificate reference)
---
## 2. Invoice Builder
### Invoice Number Format
```
[PREFIX]-[YEAR].[MONTH].[SEQUENCE]
Example: INV-2026.02.001
```
Configurable prefix per business line:
- `INV` = standard invoice
- `PRO` = proforma / quote
- `REC` = recurring invoice
- `CN` = credit note
### Invoice Template
When generating an invoice, structure it as:
```
╔══════════════════════════════════════════════════════════╗
║ [YOUR COMPANY NAME] ║
║ [Address Line 1] ║
║ [City, State ZIP] ║
║ [Country] ║
║ Tax ID: [YOUR TAX ID] ║
╠══════════════════════════════════════════════════════════╣
║ ║
║ INVOICE [NUMBER] Date: [ISSUE DATE] ║
║ Due: [DUE DATE] ║
║ ║
║ Bill To: Payment Terms: ║
║ [CLIENT NAME] [Net-30 / etc.] ║
║ [Client Address] ║
║ [City, State ZIP] PO Number: ║
║ Tax ID: [CLIENT TAX ID] [If applicable] ║
║ ║
╠══════════════════════════════════════════════════════════╣
║ # │ Description │ Qty │ Rate │ Amount ║
╠═════╪══════════════════════╪═════╪═════════╪════════════╣
║ 1 │ [Service/Product] │ 1 │ $X,XXX │ $X,XXX.XX ║
║ 2 │ [Service/Product] │ 3 │ $XXX │ $X,XXX.XX ║
║ 3 │ [Expense passthrough]│ 1 │ $XXX │ $XXX.XX ║
╠═════╧══════════════════════╧═════╧═════════╧════════════╣
║ Subtotal: $XX,XXX.XX ║
║ Discount: -$X,XXX.XX ║
║ Tax (X%): $X,XXX.XX ║
║ ───────────────────────── ║
║ TOTAL DUE: $XX,XXX.XX ║
╠══════════════════════════════════════════════════════════╣
║ Payment Methods: ║
║ • Bank Transfer: [Bank] | Acct: [XXXX] | Routing: [XX] ║
║ • PayPal: [email] ║
║ • Stripe: [payment link] ║
║ • Bitcoin: [address] / Lightning: [LNURL] ║
║ ║
║ Notes: [Custom message / thank you / late fee notice] ║
╚══════════════════════════════════════════════════════════╝
```
### Line Item Types
- **Time-based**: Hours × hourly rate (log hours, auto-calculate)
- **Fixed fee**: Project milestones, retainers
- **Quantity-based**: Units × unit price
- **Expense passthrough**: At-cost or with markup %
- **Discount line**: Negative amount (early payment, volume, loyalty)
- **Recurring**: Auto-populated from recurring schedule
### Tax Handling Decision Tree
```
Is client in same country as you?
├── YES → Apply local tax rate
│ ├── Client tax-exempt? → Add exemption reference, 0% tax
│ └── Client NOT exempt → Apply standard rate
└── NO → Usually 0% (reverse charge / export)
├── Both in EU? → Reverse charge mechanism (0%, note on invoice)
├── US interstate? → Check nexus rules
└── International → 0% with export reference
```
### Discount & Pricing Framework
- **Early payment**: 2/10 Net 30 (2% discount if paid within 10 days)
- **Volume**: Tiered pricing (1-10 units = $X, 11-50 = $Y, 51+ = $Z)
- **Loyalty**: After 6+ invoices, offer 5% ongoing discount
- **Bundled**: Package multiple services, discount 10-15% vs à la carte
- **Seasonal**: Q4 premium (+10%), Q1 discount (-5%) if applicable
---
## 3. Invoice Lifecycle & Status Tracking
### Status Flow
```
DRAFT → SENT → VIEWED → PARTIALLY_PAID → PAID → CLOSED
↓
OVERDUE → ESCALATED → WRITTEN_OFF
↓
DISPUTED → RESOLVED → PAID
```
### Invoice Ledger (YAML)
```yaml
# invoices.yaml
invoices:
- number: "INV-2026.02.001"
client_id: "CLI-001"
status: "sent"
issue_date: "2026-02-13"
due_date: "2026-03-15"
currency: "USD"
subtotal: 5000.00
discount: 0
tax: 0
total: 5000.00
amount_paid: 0
balance_due: 5000.00
payment_terms: "net-30"
line_items:
- description: "AI Integration Consulting — February"
qty: 20
rate: 250.00
amount: 5000.00
payments: []
notes: ""
sent_date: "2026-02-13"
reminders_sent: 0
created: "2026-02-13T10:30:00Z"
```
### Payment Recording
When a payment comes in:
```yaml
payments:
- date: "2026-03-10"
amount: 5000.00
method: "bank_transfer" # bank_transfer, stripe, paypal, btc, cash, check
reference: "TXN-ABC123"
notes: "Paid in full"
```
Update: `amount_paid`, `balance_due`, `status` (→ paid if balance = 0, → partially_paid if balance > 0)
---
## 4. Recurring Invoices
### Schedule Configuration
```yaml
recurring:
- id: "REC-001"
client_id: "CLI-001"
description: "Monthly Retainer — AI Ops Support"
frequency: "monthly" # weekly, biweekly, monthly, quarterly, annually
day_of_month: 1 # 1-28 (avoid 29-31 for safety)
line_items:
- description: "AI Operations Retainer"
qty: 1
rate: 3500.00
auto_send: true # false = create as draft
start_date: "2026-01-01"
end_date: null # null = indefinite
next_invoice: "2026-03-01"
invoices_generated: 2
active: true
```
### Recurring Invoice Routine (run on schedule)
1. Check `recurring` entries where `next_invoice <= today` and `active = true`
2. For each: generate invoice from template, assign next number
3. If `auto_send = true` → mark as sent, notify client
4. If `auto_send = false` → save as draft, notify user for review
5. Update `next_invoice` to next occurrence
6. Log in daily memory
---
## 5. Overdue Management & Collections
### Reminder Schedule
| Days After Due | Action | Tone |
|---|---|---|
| +1 day | Friendly reminder email | "Just a gentle reminder..." |
| +7 days | Follow-up with invoice attached | "Following up on..." |
| +14 days | Firm reminder, mention late fee | "This invoice is now 14 days past due..." |
| +30 days | Final notice before escalation | "Final notice — please remit payment..." |
| +45 days | Escalate to human (Kalin/Christina) | Flag for personal outreach |
| +60 days | Consider write-off or collections | Business decision |
### Reminder Templates
**Day +1 (Friendly)**
```
Subject: Friendly reminder — Invoice [NUMBER] due [DATE]
Hi [CONTACT],
Hope all is well! Just a quick reminder that invoice [NUMBER] for [AMOUNT] was due on [DATE].
If you've already sent payment, please disregard this note.
Payment details are on the attached invoice. Let me know if you need anything.
Best,
[YOUR NAME]
```
**Day +14 (Firm)**
```
Subject: Invoice [NUMBER] — 14 days overdue ([AMOUNT])
Hi [CONTACT],
Invoice [NUMBER] for [AMOUNT] is now 14 days past the due date of [DATE].
Per our agreement, a late fee of [X]% may apply to balances outstanding beyond [Y] days.
Could you confirm when we can expect payment? Happy to discuss if there's an issue.
Thanks,
[YOUR NAME]
```
**Day +30 (Final)**
```
Subject: Final notice — Invoice [NUMBER] overdue ([AMOUNT])
Hi [CONTACT],
This is a final reminder that invoice [NUMBER] for [AMOUNT] remains unpaid, now 30 days past the due date.
Please arrange payment within the next 7 business days to avoid further action.
If there's a dispute or issue with this invoice, please let me know immediately so we can resolve it.
Regards,
[YOUR NAME]
```
### Late Fee Calculation
```
Standard: 1.5% per month on overdue balance (18% APR)
Grace period: 5 business days after due date
Compound: Simple interest (not compound)
Cap: 25% of invoice total (or local legal maximum)
Formula: late_fee = balance_due × (monthly_rate / 30) × days_overdue
Example: $5,000 × (0.015 / 30) × 14 = $35.00
```
---
## 6. Financial Reporting
### Revenue Dashboard (generate weekly/monthly)
```
═══ REVENUE SUMMARY — [MONTH YEAR] ═══
Invoiced This Month: $XX,XXX.XX ([N] invoices)
Collected This Month: $XX,XXX.XX ([N] payments)
Outstanding (not overdue): $XX,XXX.XX ([N] invoices)
Overdue: $XX,XXX.XX ([N] invoices, avg [X] days late)
Written Off (YTD): $XX,XXX.XX
Collection Rate: XX.X% (collected / invoiced, trailing 90 days)
Avg Days to Pay: XX days (trailing 90 days)
Avg Invoice Size: $X,XXX.XX
═══ TOP CLIENTS (by revenue, YTD) ═══
1. [Client] — $XX,XXX ([N] invoices, avg [X] days to pay)
2. [Client] — $XX,XXX ([N] invoices, avg [X] days to pay)
3. [Client] — $XX,XXX ([N] invoices, avg [X] days to pay)
═══ AGING REPORT ═══
Current (not yet due): $XX,XXX ([N] invoices)
1-15 days overdue: $XX,XXX ([N] invoices)
16-30 days overdue: $XX,XXX ([N] invoices)
31-60 days overdue: $XX,XXX ([N] invoices)
60+ days overdue: $XX,XXX ([N] invoices) ⚠️
═══ MONTHLY TREND ═══
Jan: $XX,XXX ████████████
Feb: $XX,XXX ████████████████
Mar: $XX,XXX ██████████
...
═══ ACTIONS NEEDED ═══
• [N] invoices need reminder emails
• [N] recurring invoices due for generation
• [Client] has disputed INV-XXXX — needs resolution
```
### Key Metrics to Track
- **Collection Rate**: % of invoiced amount actually collected (target: >95%)
- **DSO (Days Sales Outstanding)**: avg days from invoice to payment (target: <30)
- **Overdue Ratio**: overdue balance / total outstanding (target: <10%)
- **Revenue Concentration**: % from top client (flag if >40% — dependency risk)
- **MRR from Recurring**: recurring invoice total / month
---
## 7. Credit Notes & Adjustments
When a refund or correction is needed:
```yaml
credit_note:
number: "CN-2026.02.001"
original_invoice: "INV-2026.01.003"
client_id: "CLI-001"
reason: "Partial refund — service hours overcharged"
line_items:
- description: "Correction: 5 hours overcharged"
qty: -5
rate: 250.00
amount: -1250.00
total: -1250.00
issued: "2026-02-13"
```
Apply credit notes against:
1. The original invoice (reduce balance)
2. Future invoices (credit on account)
3. Direct refund (record refund method + reference)
---
## 8. Multi-Currency Support
```yaml
currencies:
primary: "USD"
accepted: ["USD", "GBP", "EUR", "BTC"]
exchange_rates: # Update weekly or use live rates
GBP_USD: 1.27
EUR_USD: 1.08
BTC_USD: 97500
conversion_note: "Converted at rate on invoice date. Payment accepted in invoiced currency only."
```
Rules:
- Always invoice in the client's preferred currency
- Record payments in the currency received
- Convert to primary currency for reporting (use rate on payment date)
- Note exchange rate on invoice if cross-currency
- BTC/Lightning: include both sats and fiat equivalent
---
## 9. Quote-to-Invoice Pipeline
### Quote (Proforma) Template
Same as invoice template but:
- Prefix: `PRO-` instead of `INV-`
- Header: "QUOTATION" instead of "INVOICE"
- Add: "Valid until: [DATE]" (typically 30 days)
- Add: "This is not a tax invoice"
### Pipeline Flow
```
QUOTE → ACCEPTED → INVOICE → PAID
↓
EXPIRED (auto-expire after validity period)
↓
REVISED (new version with changes)
```
When a quote is accepted:
1. Convert to invoice (change prefix, remove validity notice)
2. Assign invoice number
3. Set payment terms based on client profile
4. Send invoice
5. Archive quote as "converted"
---
## 10. Edge Cases & Rules
### Partial Payments
- Record each payment separately with reference
- Update balance_due after each payment
- On final payment → mark PAID
- If partial + overdue → chase remaining balance only
### Disputed Invoices
- Mark status as DISPUTED
- Record dispute reason and date
- Pause reminders during dispute
- Track resolution (adjusted, credit note, or confirmed correct)
- Resume billing after resolution
### Void vs Credit Note
- **Void**: Invoice was sent in error, never should have existed → mark VOIDED, exclude from reports
- **Credit Note**: Services were delivered but need adjustment → issue CN, include in reports
### Tax Invoice Requirements (by region)
- **US**: No strict format, but include EIN if registered
- **UK/EU**: Must include VAT number, VAT amount, "reverse charge" note if applicable
- **Australia**: Must say "Tax Invoice", include ABN, GST amount
- **Canada**: Include GST/HST number, province-specific rules
### Rounding
- Always round line item amounts to 2 decimal places
- Calculate tax on subtotal (not per-line) to avoid penny discrepancies
- Display currency symbol before amount: $1,234.56
### Invoice Numbering
- NEVER reuse or skip numbers (tax audit requirement)
- Sequential within each prefix
- If voided, keep the number, just mark status
---
## 11. Automation Opportunities
Set up cron jobs or heartbeat checks for:
- [ ] Generate recurring invoices on schedule
- [ ] Send overdue reminders per the schedule above
- [ ] Weekly revenue dashboard to owner
- [ ] Monthly aging report
- [ ] Auto-flag clients with >45 days overdue
- [ ] Quarterly review: update exchange rates, review pricing
---
## 12. Export Formats
When the user needs to export:
- **CSV**: For spreadsheet / accounting import
```
invoice_number,client,date,due_date,total,status,amount_paid,balance
```
- **JSON**: For API integration or backup
- **Markdown table**: For quick review in chat
- **PDF-ready text**: Formatted text block ready for PDF generation tool
---
## Commands Reference
| Command | Action |
|---|---|
| "Invoice [client] for [amount/description]" | Create new invoice |
| "Quote [client] for [service]" | Create proforma |
| "Show outstanding invoices" | List unpaid invoices |
| "What's overdue?" | Aging report, overdue only |
| "Revenue this month" | Monthly revenue dashboard |
| "Send reminder for [invoice]" | Generate reminder email |
| "Record payment [invoice] [amount]" | Log payment received |
| "Recurring: [client] [amount] [frequency]" | Set up recurring invoice |
| "Credit note for [invoice]" | Issue credit/adjustment |
| "Client report [name]" | Full client payment history |
| "Export invoices [format]" | CSV/JSON/Markdown export |
| "Void [invoice]" | Void an invoice |
| "Update rates" | Refresh exchange rates |
don't have the plugin yet? install it then click "run inline in claude" again.