Agent Invoice

Invoicing, billing, and payment tracking for autonomous AI agents

MCP server + CLI + REST API for autonomous agents to generate, track, and manage invoices.

Built for the agentic economy — by Nyx Builds.

MCP Server Setup

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "agent-invoice": {
      "command": "uvx",
      "args": ["agent-invoice", "serve"]
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "agent-invoice": {
      "command": "uvx",
      "args": ["agent-invoice", "serve"]
    }
  }
}

Any MCP host: command: uvx, args: ["agent-invoice", "serve"]

Why?

Agents do work. Agents need to get paid. But there's no standard way for an autonomous agent to:

• Generate an invoice for completed work

• Track payment status across clients

• Maintain a ledger of earnings

• Integrate billing into their workflow via MCP

• Bill in multiple currencies with tax calculations

• Set up recurring invoices for retainer clients

• Chase overdue payments automatically

• Issue credit notes and refunds

• Generate client statements

Agent Invoice fixes this. It's a self-contained billing system designed for AI agents.

Related MCP server: mcp-ai-fiskalizacija

Features

• 📄 Invoice Generation — Create professional invoices with line items, due dates, and client info

• 💰 Tax Calculation — Per-line-item and invoice-level tax rates with automatic computation

• 💱 Multi-Currency — 15+ currencies (USD, EUR, GBP, JPY, etc.) with proper symbols and decimal handling

• 💳 Partial Payments — Record multiple payments against an invoice, track remaining balance

• 📝 Credit Notes — Issue credits/refunds, apply them to invoices, track applications

• 📊 Client Statements — Period financial statements with opening/closing balances

• 🔄 Recurring Invoices — Set up weekly, biweekly, monthly, quarterly, or yearly billing templates

• ⏰ Dunning Automation — Automated overdue reminders with configurable escalation levels

• 🔍 Invoice Search — Search by text, date range, amount range, status, client, currency

• 📋 Invoice Templates — Built-in and custom templates for quick invoice creation

• 📑 Estimates & Quotes — Create quotes, send, accept/decline, and convert to invoices

• 📊 A/R Aging Reports — Track outstanding receivables by aging buckets (0-30, 31-60, 61-90, 90+ days)

• 📈 Revenue Analytics — Monthly revenue trends, collection rate, avg days to pay, top clients

• 🏷️ Custom Numbering — Configurable invoice numbering (prefix, separator, digits)

• 📊 Payment Tracking — Monitor which invoices are pending, paid, partially paid, or overdue

• 📒 Earnings Ledger — Running total of all income, tax, and discounts across invoices

• 📤 Export — Export invoices as PDF, JSON, or Markdown

• 🤖 Usage Metering (v0.8.0) — Track AI/API consumption (tokens, cost, provider, model) and bill clients based on actual usage

• 💸 Usage-Based Billing (v0.8.0) — Aggregate usage events into invoices with per-provider/model line items and optional markup

• 📊 Cost Analytics (v0.9.0) — Cost trends, projections, anomaly detection, model efficiency scoring, and provider comparison

• 💰 Late Fee Engine (v1.1.0) — Configurable late payment penalties (fixed, percentage, compound) with grace periods, recurring accrual, fee caps, waive/forgive, and analytics

• 🏷️ Promo Codes & Discounts (v1.2.0) — Promotional codes (percentage/fixed) with usage limits, expiry, client/currency restrictions, minimum spend; tiered volume discounts; early payment terms (2/10 net 30); redemption analytics

• 🔌 MCP Server — 128 tools for full billing integration via Model Context Protocol

• 🌐 REST API — Full HTTP API with FastAPI for web integration

• 💻 CLI — Command-line interface with 40+ commands for direct use or scripting

• 💾 JSON Storage — Simple file-based storage, no database required

Quick Start

CLI Usage

# Create a client (with EUR as default billing currency)
agent-invoice client add "Acme Corp" --email billing@acme.com --currency EUR

# Create an invoice with tax
agent-invoice create \
  --client "Acme Corp" \
  --item "Code review,40,150.00,8.5" \
  --item "Bug fixes,10,200.00" \
  --tax-rate 8.5 \
  --due 30

# Apply a discount
agent-invoice discount INV-0001 50.00

# Record a partial payment
agent-invoice payment add INV-0001 --amount 500.00 --method bank_transfer

# List all invoices in EUR
agent-invoice list --currency EUR

# Search invoices
agent-invoice list --search "consulting" --min-amount 500.0
agent-invoice list --status overdue
agent-invoice list --date-from 2026-01-01 --date-to 2026-06-30

# Mark an invoice as paid
agent-invoice pay INV-0001

# Show earnings summary
agent-invoice earnings

# Export to PDF
agent-invoice export INV-0001 --format pdf --company-name "My Agent Co"

# --- Recurring invoices ---
agent-invoice recurring create \
  --client "Acme Corp" \
  --item "Retainer,1,500.00" \
  --frequency monthly

agent-invoice recurring generate REC-ABC123
agent-invoice recurring process    # Generate all due

# --- Credit notes ---
agent-invoice credit create --client "Acme Corp" --amount 250.00 --reason "overpayment"
agent-invoice credit apply CN-ABC123 --invoice INV-0001
agent-invoice credit list --status open

# --- Client statements ---
agent-invoice statement "Acme Corp" 2026-01-01 2026-06-30

# --- Estimates & Quotes ---
agent-invoice estimate create "Acme Corp" --description "Website redesign" --quantity 1 --price 5000.00 --terms "Net 30"
agent-invoice estimate create "Acme Corp" --description "Monthly support" --price 2000.00 --expiry 15 --tax-rate 8.5
agent-invoice estimate list --status draft
agent-invoice estimate show EST-ABC123
agent-invoice estimate send EST-ABC123
agent-invoice estimate accept EST-ABC123
agent-invoice estimate convert EST-ABC123 --due-days 30

# --- A/R Aging Report ---
agent-invoice ar-aging
agent-invoice ar-aging --currency USD

# --- Revenue Analytics ---
agent-invoice revenue
agent-invoice revenue --months 12 --currency USD

# --- Dunning (overdue reminders) ---
agent-invoice dunning config
agent-invoice dunning send INV-0001
agent-invoice dunning process    # Auto-send reminders for all overdue

# --- Templates ---
agent-invoice template list
agent-invoice template use TPL-HOURLY --client "Acme Corp"

# --- Numbering ---
agent-invoice numbering set --prefix BIL --separator / --digits 3

# List supported currencies
agent-invoice currencies

MCP Server

Start the MCP server for integration with any MCP-compatible agent:

agent-invoice serve

The server exposes 55 tools:

Invoices & Line Items:

• create_invoice — Generate a new invoice (with tax, currency, discounts)

• list_invoices — List invoices with filtering (status, client, currency)

• get_invoice — Get details of a specific invoice

• mark_paid / mark_sent / cancel_invoice — Status management

• apply_discount — Apply a discount

• add_line_item / remove_line_item — Edit draft invoices

• search_invoices — Search by text, date range, amount range

• export_invoice — Export as markdown, JSON, or PDF

Payments:

• record_payment — Record a payment (full or partial)

• list_payments / remove_payment — Payment management

Clients:

• add_client — Register a client (with default currency)

• update_client / list_clients — Client management

• client_statement — Generate period financial statements

Credit Notes:

• create_credit_note — Issue a credit/refund

• list_credit_notes / get_credit_note — View credit notes

• apply_credit_note — Apply credit to an invoice

• void_credit_note / remove_credit_note — Void or delete

Recurring:

• create_recurring — Create a recurring invoice template

• list_recurring / generate_from_recurring

• pause_recurring / resume_recurring / process_due_recurring

Templates:

• list_templates / get_template / create_template

• create_invoice_from_template / remove_template

Dunning:

• get_dunning_config / update_dunning_config

• send_dunning_reminder — Send a reminder for an overdue invoice

• process_overdue_dunning — Auto-process all overdue

• list_dunning_actions / remove_dunning_action

Config & Utilities:

• get_numbering_config / update_numbering_config

• earnings_summary / list_currencies

Estimates & Quotes:

• create_estimate — Create a quote with line items, tax, discount, and expiry

• list_estimates — List quotes with optional status/client filters

• get_estimate — Get full details of a specific quote

• send_estimate — Mark a quote as sent to the client

• accept_estimate / decline_estimate — Client decision tracking

• convert_estimate_to_invoice — Convert an accepted quote into an invoice

• remove_estimate — Delete a quote (cannot delete converted ones)

Reports & Analytics:

• generate_ar_aging_report — A/R aging with per-client bucket breakdown

• get_revenue_analytics — Monthly trends, collection rate, days to pay, top clients

REST API

Start the HTTP server:

uvicorn agent_invoice.api:create_app --factory --port 8000

Full CRUD API with endpoints for invoices, payments, clients, credit notes, statements, recurring, templates, dunning, estimates, reports, earnings, and currencies.

# Create a client
curl -X POST http://localhost:8000/clients \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "currency": "USD"}'

# Create an invoice
curl -X POST http://localhost:8000/invoices \
  -H "Content-Type: application/json" \
  -d '{"client": "CLT-...", "items": [{"description": "Work", "quantity": 10, "unit_price": 100}]}'

# Record a payment
curl -X POST http://localhost:8000/invoices/INV-0001/payments \
  -H "Content-Type: application/json" \
  -d '{"amount": 500.00, "method": "bank_transfer"}'

# Create an estimate
curl -X POST http://localhost:8000/estimates \
  -H "Content-Type: application/json" \
  -d '{"client": "CLT-...", "line_items": [{"description": "Project", "quantity": 1, "unit_price": 5000}]}'

# Convert an estimate to invoice
curl -X POST http://localhost:8000/estimates/EST-ABC123/convert?due_days=30

# Get A/R aging report
curl http://localhost:8000/reports/ar-aging?currency=USD

# Get revenue analytics
curl http://localhost:8000/reports/revenue?period_start=2026-01-01&period_end=2026-06-30

Tax Calculation

Agent Invoice supports two levels of tax:

1. Line-item tax — Set a tax rate on individual items: --item "Consulting,10,200.00,8.5"

2. Invoice-level tax — Set a default tax rate for items without their own: --tax-rate 8.5

Items with their own tax rate override the invoice-level rate. The grand total is computed as:

Subtotal + Total Tax - Discount = Grand Total

Credit Notes

Issue credits for overpayments, refunds, or billing errors:

# Create a credit note
agent-invoice credit create --client "Acme Corp" --amount 250.00 --reason "overpayment"

# Apply to an invoice (reduces balance)
agent-invoice credit apply CN-ABC123 --invoice INV-0001

# Apply partial amount
agent-invoice credit apply CN-ABC123 --invoice INV-0001 --amount 100.00

# Void a credit note (only if unapplied)
agent-invoice credit void CN-ABC123

Client Statements

Generate financial statements showing all activity for a period:

agent-invoice statement "Acme Corp" 2026-01-01 2026-06-30

Shows opening balance, period invoices, payments, credit notes, and closing balance.

Dunning (Overdue Management)

Automated escalation reminders for overdue invoices:

# Configure dunning thresholds (days after due date)
agent-invoice dunning config --first 7 --second 14 --final 30

# Send a reminder for a specific invoice
agent-invoice dunning send INV-0001

# Auto-process all overdue invoices (run daily via cron)
agent-invoice dunning process

Multi-Currency

Set a default currency per client, or override per invoice:

# Client with EUR default
agent-invoice client add "Berlin GmbH" --currency EUR

# Override to GBP for a specific invoice
agent-invoice create --client "Berlin GmbH" --currency GBP --item "Work,100.00"

Supported currencies: USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, INR, BRL, KRW, MXN, SGD, SEK, NZD

Invoice Search

Find invoices by text, amount, or date:

# Text search (matches ID, client name, notes, line item descriptions)
agent-invoice list --search "consulting"

# Amount range
agent-invoice list --min-amount 500.0 --max-amount 5000.0

# Date range
agent-invoice list --date-from 2026-01-01 --date-to 2026-06-30

# Combined filters
agent-invoice list --search "API" --status overdue --min-amount 100.0

Estimates & Quotes

Send quotes before work begins, then convert accepted quotes into invoices:

# Create an estimate with tax and expiry
agent-invoice estimate create "Acme Corp" \
  --description "Website redesign" \
  --quantity 1 \
  --price 5000.00 \
  --tax-rate 8.5 \
  --expiry 30 \
  --terms "Net 30"

# Send the quote to the client
agent-invoice estimate send EST-ABC123

# Client accepts
agent-invoice estimate accept EST-ABC123

# Convert to a real invoice
agent-invoice estimate convert EST-ABC123 --due-days 30

# List all estimates by status
agent-invoice estimate list --status accepted

Estimates have a full lifecycle: draft → sent → accepted/declined → converted. Expired quotes are auto-detected. Converted estimates link back to the invoice they became.

A/R Aging Reports

Track outstanding receivables grouped by how long they've been overdue:

# Full aging report
agent-invoice ar-aging

# Filter by currency
agent-invoice ar-aging --currency USD

Groups outstanding balances into standard aging buckets: 0-30, 31-60, 61-90, 90+ days. Shows per-client breakdown with invoice-level detail (days overdue, amount remaining).

Revenue Analytics

Analyze revenue trends over time:

# Last 6 months (default)
agent-invoice revenue

# Last 12 months
agent-invoice revenue --months 12

Shows monthly invoicing vs. collection trends, overall collection rate (%), average days to pay, fastest/slowest payments, and top clients by revenue.

Installation

pip install agent-invoice

Or with uv:

uv pip install agent-invoice

Architecture

agent-invoice/
├── src/agent_invoice/
│   ├── __init__.py
│   ├── models.py       # Pydantic models (Invoice, Client, CreditNote, Estimate, ARAging, RevenueAnalytics, etc.)
│   ├── store.py        # JSON file storage with numbering config
│   ├── service.py      # Business logic layer (50+ methods)
│   ├── cli.py          # Click CLI with 40+ commands
│   ├── mcp_server.py   # MCP server with 101 tools
│   ├── api.py          # FastAPI REST API
│   └── pdf.py          # PDF export with reportlab
├── tests/              # 413 tests (models, store, service, CLI, API, MCP, estimates, reports)
└── data/               # Default storage location

Data Storage

Invoices, clients, recurring templates, credit notes, dunning actions, and templates are stored as JSON files in ~/.agent-invoice/ by default. Set the AGENT_INVOICE_DIR environment variable to customize the location.

License

MIT

Changelog

v1.2.0 — Discount & Promotion Engine

Promo codes, tiered volume discounts, early payment terms, and redemption analytics — the complete discount layer for agentic billing.

Every billing platform needs promotional discounts to drive conversions, volume-based pricing for B2B, and early payment incentives for cash flow. Now agent-invoice does too.

• Promo Codes: Redeemable codes with percentage or fixed-amount discounts

  • Usage limits: global redemption cap and per-client cap

  • Validity window: start date, expiry date

  • Restrictions: minimum spend, client whitelist, currency whitelist, max discount cap

  • Lifecycle: active → paused → expired/exhausted (auto-transitions)

  • Case-insensitive code lookup with auto-normalization

• Tiered Volume Discounts: Subtotal-based discount schedules

  • Multiple tiers (e.g., Bronze ≥$100 = 5%, Silver ≥$500 = 10%, Gold ≥$1000 = 15%)

  • Best qualifying tier automatically selected

  • Percentage or fixed-amount per tier with custom labels

• Early Payment Discounts: "2/10 net 30" terms attached to invoices

  • Configurable discount percentage and payment window

  • Terms travel with the invoice (stored in notes)

  • Real-time eligibility calculation with days remaining

• Discount Redemption Tracking: Every discount application recorded

  • Source type (promo, volume, early_payment, manual)

  • Original vs. final subtotal, client, currency

• Discount Analytics Dashboard: Comprehensive summary

  • Total discount given, redemption count, avg per redemption

  • Breakdowns by source type, top promo codes, discounts by client

  • Revenue impact percentage (discount / (discount + collected))

• 15 new MCP tools (128 total), 21 new REST API endpoints, 87 new tests (791 total, all passing)

v1.1.0 — Late Fee Engine

Automated late payment penalties for overdue invoices — configurable policies with fixed, percentage, or compound fees.

Every major billing platform (Stripe, QuickBooks, FreshBooks, Xero) supports late fees. Now agent-invoice does too — fully integrated with the existing dunning (reminder) system.

• Late Fee Policies: Configurable rules governing how penalties are applied

  • Fee types: fixed ($25 flat), percentage (1.5% of outstanding), or compound ($25 + 1.5%)

  • Frequency: one-time, daily, weekly, or monthly accrual

  • Grace period (configurable days before fees start)

  • Maximum total fees cap (safety valve per invoice)

  • Minimum outstanding amount threshold

  • Exempt invoice statuses (draft, cancelled)

• Automatic Application: apply_late_fee for single invoices, process_overdue_late_fees for batch processing

• Waive & Forgive: Waive individual late fees with reason tracking

• Late Fee Analytics: Comprehensive summary dashboard — total charged/pending/paid/waived, breakdowns by policy and client, top late payers

• Multi-currency: Fees charged in invoice's native currency

• Integration: Coexists with dunning — reminders and penalties work independently

• 12 new MCP tools (113 total), 14 new REST API endpoints, 7 new CLI commands

• 62 new tests (704 total, all passing)

v1.0.0 — Rate Cards & Subscriptions (Recurring Billing)

The first MCP server to unify usage metering → automatic cost calculation → subscription billing → invoicing.

• Rate Cards: Define per-token pricing for any provider+model (OpenAI, Anthropic, etc.). Record usage with just tokens — the rate card calculates the cost automatically. No manual cost entry.

  • Per-million-token rates: input, output, cache-read, cache-write

  • Per-request flat surcharge support

  • Multiple rate cards (production, enterprise, dev) with activate/deactivate

• Subscriptions: Full recurring billing lifecycle — plans, trial periods, active/past-due/canceled/paused states, automatic invoice generation per billing cycle.

  • Plan catalogs with tiered pricing (daily/weekly/monthly/quarterly/yearly)

  • Trial support with configurable duration

  • Pause/resume, cancel with effective dates

  • Auto-invoice generation on cycle renewal

• MRR Reporting: Monthly recurring revenue summaries, subscription growth metrics, churn tracking.

• Batch Usage Recording: Log hundreds of usage events in a single call with automatic cost calculation via rate cards.

• 22 new MCP tools (101 total), 66 new tests (642 total, all passing).

v0.9.0 — Usage Analytics & Cost Intelligence

• Provider cost analysis, model comparison, cost trends, anomaly detection

• 5 new analytics MCP tools

v0.8.0 — Usage Metering & Agent Billing

• UsageEvent model, usage summaries, aggregate → invoice → mark billed lifecycle

• Markup support for reseller margins

• 6 new metering MCP tools