API Documentation

Everything you need to create and manage invoices programmatically. Works with REST, MCP (Claude, ChatGPT), and WebMCP (browser agents).

OpenAPI Spec | MCP Manifest | Health Check

Authentication

Write operations require authentication via API key. Read operations (invoices.query, templates.query, iv.capabilities) work without auth.

1. Get an API key

Go to Settings and generate an API key. Keys start with iv_.

2. Include in requests

Pass it as a Bearer token in the Authorization header:

Authorization: Bearer iv_your_api_key_here

Endpoints

GET /api/health

Health check. No auth required.

Example response

{
  "status": "ok",
  "version": "0.1.0",
  "d1": true,
  "r2": true,
  "kv": true,
  "timestamp": "2026-04-07T12:00:00.000Z"
}

GET /api/invoices

List invoices with optional filters.

Query parameters

type invoice | credit_note | quote | purchase_order

client_id Filter by client ID

from_date ISO date (YYYY-MM-DD)

to_date ISO date (YYYY-MM-DD)

limit 1-100, default 20

offset default 0

POST /api/invoices

Create a new invoice. Totals are calculated automatically from line items.

Example request

{
  "from_name": "Acme Corp",
  "bill_to_name": "Client Inc",
  "currency": "USD",
  "locale": "en",
  "issue_date": "2026-04-07",
  "due_date": "2026-05-07",
  "payment_terms": "Net 30",
  "items": [
    { "description": "Web development", "quantity": 40, "rate": 15000 },
    { "description": "Design review", "quantity": 5, "rate": 12000 }
  ],
  "tax_rate": 8.5,
  "notes": "Thank you for your business!"
}

Required fields

from_name Your name or company (1-500 chars)

bill_to_name Client name (1-500 chars)

currency ISO 4217 code (e.g. USD, EUR)

locale BCP 47 locale (e.g. en, es, fr)

issue_date ISO date (YYYY-MM-DD)

GET /api/invoices/:id

Get full invoice details including all line items.

PUT /api/invoices/:id

Update any fields. Totals are recalculated. All fields are optional.

DELETE /api/invoices/:id

Permanently delete an invoice.

POST /api/invoices/:id/export

Generate a PDF and get the download URL.

GET /api/clients

List clients. Optional ?q= search by name or email.

POST /api/clients

Create a client. Only name is required.

GET /api/templates

List available invoice templates (built-in and custom).

POST /api/brand-extract

Extract brand colors, fonts, and logo from a website URL.

x402: $0.01 per request for agents

GET /api/dashboard

Get dashboard statistics: total invoices, revenue, outstanding, overdue.

Error format

All errors follow a consistent structure with machine-readable codes:

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "details": { "field": "from_name", "issue": "required" }
}

Common error codes

UNAUTHORIZED Missing or invalid API key (401)

FORBIDDEN Not your resource (403)

NOT_FOUND Resource does not exist (404)

VALIDATION_ERROR Invalid request body (422)

PAYMENT_REQUIRED x402 payment needed (402)

INTERNAL_ERROR Server error (500)

x402 pricing

Most API operations are free. Some operations use the x402 protocol for micropayments:

Operation	Price
Create / update / delete invoice	Free
List / get invoices	Free
PDF generation	Free
Client management	Free
Brand extraction	$0.01

MCP setup

AI agents (Claude, ChatGPT, Copilot) can use iv via the Model Context Protocol.

1. Point your agent to the MCP manifest

https://freeinvoicemaker.app/.well-known/mcp.json

2. Configure authentication

The agent needs your API key. In Claude Desktop, add to your MCP config:

{
  "mcpServers": {
    "iv": {
      "url": "https://freeinvoicemaker.app/api/mcp",
      "headers": {
        "Authorization": "Bearer iv_your_api_key"
      }
    }
  }
}

3. Available tools (20 v2 tools)

Invoice lifecycle

invoices.create Create a complete invoice in one call

invoices.query List, search, or get invoices

invoices.mutate Update, transition status, or delete

invoices.export Export to 14 formats (PDF, DOCX, UBL, ZUGFeRD...)

invoices.send Send via email with PDF attachment

invoices.finalize Lock invoice (undo supported)

invoices.duplicate Clone with new number and date

invoices.createFromDsl Create from DSL (~40% fewer tokens than JSON)

invoices.automate Recurring rules and webhooks

AI-native

invoices.summarize Natural language invoice summary

invoices.suggest Suggest items/rates from history

invoices.analytics Revenue analytics and aging buckets

Templates & entities

templates.query List or get templates

templates.mutate Create or batch-edit templates

templates.apply Apply template to invoice

entities.query Query clients or products

entities.mutate Create, update, or delete clients/products

import Import from 16 formats (CSV, UBL, vCard...)

Platform

iv.capabilities Self-documenting catalog (no auth)

iv.feedback Submit bugs or feature requests (no auth)

WebMCP (browser agents)

Browser-based agents can discover tools via WebMCP. The manifest is at:

https://freeinvoicemaker.app/.well-known/webmcp.json

WebMCP-enabled pages include data-tool-* attributes on interactive elements, allowing agents to understand and interact with the UI directly.

DSL format

The invoices.createFromDsl tool accepts a compact text format that uses ~40% fewer tokens than the JSON equivalent. Ideal for LLM-generated invoices.

INVOICE INV-2026-0043
FROM Acme Design Co. | 123 Studio Lane
TO Globex Corp | ap@globex.com
DATE 2026-04-09
DUE 2026-05-09
CURRENCY USD
TAX US-TX
ITEMS
  Website redesign    1 × $8,500.00
  SEO audit           1 × $2,250.00
FINALIZE
SEND ap@globex.com

~100 tokens. Equivalent JSON is ~400 tokens. Supports FINALIZE and SEND directives to lock and email the invoice in the same call.

curl example

curl -X POST https://freeinvoicemaker.app/api/mcp \
  -H "Authorization: Bearer iv_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "invoices.createFromDsl",
    "params": {
      "dsl": "INVOICE INV-2026-0043\nFROM Acme Design Co.\nTO Globex Corp\nDATE 2026-04-09\nDUE 2026-05-09\nCURRENCY USD\nITEMS\n  Consulting  10 × $150.00"
    }
  }'

Try it

GET/api/health