---
title: "Invoice API for developers and AI agents — One Page Invoice"
description: "Create PDF invoices or shareable invoice links with a Pay button from code or an AI assistant. Free, no API key: JSON in, PDF or link out. OpenAPI spec included."
image: "https://onepageinvoice.com/og/docs.png"
---

Developers and AI assistants

# API

Make one-page invoices from code or from an AI assistant: a shareable page with a Pay button and the PDF, or just the PDF. No account and no API key. JSON in; JSON or PDF out.

Machine-readable: [/openapi.json](https://onepageinvoice.com/openapi.json) (OpenAPI 3.1) · this page as Markdown: [/docs/api.md](https://onepageinvoice.com/docs/api.md) · Agent Skill: [SKILL.md](https://onepageinvoice.com/skills/onepageinvoice/SKILL.md)

## Quick start

Create an invoice behind a share link:

```bash
curl -sS https://onepageinvoice.com/api/v1/invoices \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "0042", "date": "2026-11-05", "due_date": "2026-11-19", "currency": "USD",
    "from": {"name": "Ada Ferreira", "email": "ada@ferreira.studio"},
    "to": {"name": "Castelo Bakery Lda"},
    "items": [{"description": "Site survey and measurements", "quantity": 1, "unit_price": 450}],
    "payment_instructions": ["Bank transfer: IBAN PT50 0002 0123 1234 5678 9015 4"]
  }'
```

Response (`201 Created`):

```json
{
  "id": "u2q6m74sticimboa",
  "url": "https://onepageinvoice.com/i/u2q6m74sticimboa",
  "pdf_url": "https://onepageinvoice.com/i/u2q6m74sticimboa.pdf",
  "edit_url": "https://onepageinvoice.com/new#id=u2q6m74sticimboa&token=…",
  "edit_token": "…",
  "expires_at": "2026-12-05T17:18:22Z"
}
```

`url` is the page your client opens: the amount, the PDF, your payment instructions, and a Pay button when you send a `payment_url`. Add `"link": true` and/or `"qr": true` to print the page's address or a QR code to it on the PDF. `edit_url` opens the invoice in the editor; it's private, like a password. Links expire 30 days after the last change.

Just the PDF, nothing stored:

```bash
curl -sS https://onepageinvoice.com/api/v1/pdf -H 'Content-Type: application/json' \
  -d @invoice.json -o invoice-0042.pdf
```

## Endpoints

| Method and path | What it does |
| --- | --- |
| `POST /api/v1/invoices` | Save an invoice; returns its links and the edit token (once). |
| `GET /api/v1/invoices/{id}` | Load it for editing. Needs `Authorization: Bearer <edit_token>`. |
| `PUT /api/v1/invoices/{id}` | Replace it; same link, expiry restarts. Needs the token. |
| `DELETE /api/v1/invoices/{id}` | Turn the link off and erase the invoice (the page then answers 410). Needs the token. |
| `POST /api/v1/pdf` | Render a PDF; nothing is stored. |
| `POST /api/v1/preview` | Draw a draft as SVG and list problems per field (what the editor uses). |
| `GET /i/{id}`, `GET /i/{id}.pdf` | The share page and its PDF. |

## The invoice

| Field | Type | Notes |
| --- | --- | --- |
| `number` | string | Required, up to 32 characters. |
| `date`, `due_date` | YYYY-MM-DD | Date required; due date defaults to it. |
| `currency` | string | USD (default), EUR, GBP, CAD, AUD, NZD, CHF, JPY. |
| `from` | object | `name` (required), `address` (up to 4 lines), `email`, `phone`, `website`, `tax_id`, `logo` (base64 PNG or JPEG, up to 1 MB; Classic prints it). |
| `to` | object | `name` (required), `lines` (attention and address, up to 4; note: `lines`, not `address`), `email`. |
| `items` | array | `description`, `quantity` (> 0), `unit_price` (negative = discount). At least one; Classic and Bold fit 15, Minimal 10. |
| `tax_rate` | number | Percent of the net amount, 0–100. |
| `payment_instructions` | array of strings | Up to 4 lines, e.g. bank details. |
| `payment_url` | https URL | Your Stripe, PayPal or bank link: the Pay button. Without one, the share page shows the invoice, the PDF and a button to copy your payment instructions. |
| `link`, `qr` | booleans | For saved invoices: print the online invoice's address (“Pay online: …”) and/or a QR code that opens it. Independent; both off by default. Without `link`, a `payment_url` prints as “Pay online” instead. |
| `notes` | string | Up to four lines on the page. |
| `template` | string | `classic` (default), `minimal`, `bold`. |
| `accent` | #rrggbb | Default `#5980a6`. |
| `page_size` | string | `letter` (default) or `a4` (use it outside the US and Canada). |

Required: `number`, `date`, `from.name`, `to.name` and at least one item. Unknown fields are rejected with `400`, so a typo never goes unnoticed. To check an invoice without saving anything, send it to `POST /api/v1/preview`: an empty `problems` list means it's ready.

## Errors and limits

- `422`: `{"problems": [{"field": "to.name", "message": "Add a client name…", "missing": true}]}`. Fields are JSON paths such as `items.2.unit_price`; an empty field means the whole invoice, e.g. it doesn't fit on one page.
- `400` malformed JSON or unknown field · `401`/`403` missing or wrong edit token · `404` no such invoice · `410` link turned off · `413` body over 3 MB · `429` too many saves (see `Retry-After`).
- Saves are limited per address (a burst of 30, then about one a minute). Rendering PDFs is not stored and not limited beyond fair use.

## MCP server

Add One Page Invoice to Claude, ChatGPT, Cursor or any MCP client as a remote server: `https://onepageinvoice.com/mcp` (streamable HTTP, no sign-in). In Claude, go to Settings → Connectors → Add custom connector and paste the address. In Claude Code:

```bash
claude mcp add --transport http onepageinvoice https://onepageinvoice.com/mcp
```

Clients configured with JSON:

```json
{"mcpServers": {"onepageinvoice": {"url": "https://onepageinvoice.com/mcp"}}}
```

| Tool | What it does |
| --- | --- |
| `create_invoice` | Save an invoice; returns the share link, the PDF, the private edit link and the edit token. |
| `check_invoice` | List what to fix and the totals, without saving anything. |
| `get_invoice`, `update_invoice` | Read back or replace a saved invoice (needs its edit token). A logo set in the editor is kept. |
| `list_templates` | The designs, how many items fit on each, currencies and page sizes. |

The tools take the same invoice JSON as the API, without logo and signature images, and share its limits. Nothing is sent to your client: the assistant hands you the links to review and send.

### With your account

Connect `https://onepageinvoice.com/mcp/account` instead to work with your saved sender profile, clients and invoices: “invoice Castelo Bakery for the site survey” then needs no addresses or bank details. Your client asks you to sign in (OAuth 2.1 with an email link) and to allow it; disconnect it any time under [Connected apps](https://onepageinvoice.com/account/apps).

```bash
claude mcp add --transport http onepageinvoice https://onepageinvoice.com/mcp/account
```

| Tool | What it does |
| --- | --- |
| `create_invoice` | Save an invoice to your account, filling the sender, number, dates and payment details from your profile and the client's address from your clients. A draft unless `issue` is true. |
| `list_invoices`, `get_invoice` | Your invoices, by status (`unpaid`, `draft`, `paid`…) or search. |
| `mark_paid` | Mark an issued invoice paid or unpaid. |
| `get_profile`, `list_clients` | Your sender details, defaults and next number; your client book. |

The assistant can't email your clients or delete anything.

## For AI assistants

Your users can say “invoice Castelo Bakery for the site survey” and get a link to review. Give your agent these instructions, or install the [Agent Skill](https://onepageinvoice.com/skills/onepageinvoice/SKILL.md) (save it as `.claude/skills/onepageinvoice/SKILL.md`).

For `AGENTS.md` (Codex and other agents):

```markdown
## Invoices
To make an invoice, use the One Page Invoice API (no key): POST JSON to
https://onepageinvoice.com/api/v1/invoices for a shareable invoice page with a
Pay button and PDF, or to /api/v1/pdf for just a PDF file. Reference:
https://onepageinvoice.com/docs/api.md. Ask for missing sender or client details
instead of inventing them. On 422, fix the listed fields and retry. Show the
user the share link (url), the PDF (pdf_url) and the private edit link
(edit_url); don't claim the invoice was sent.
```

Rules for agents: create drafts for the user to review and send; never invent amounts, clients or bank details; keep the edit token secret.

```json
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","item":"https://onepageinvoice.com/","name":"Home","position":1},{"@type":"ListItem","item":"https://onepageinvoice.com/docs/api","name":"Invoice API for developers and AI agents","position":2}]}
```

```json
{"@context":"https://schema.org","@type":"TechArticle","author":{"@id":"https://onepageinvoice.com/#organization"},"description":"Create PDF invoices or shareable invoice links with a Pay button from code or an AI assistant. Free, no API key: JSON in, PDF or link out. OpenAPI spec included.","headline":"Invoice API for developers and AI agents","image":"https://onepageinvoice.com/og/docs.png","inLanguage":"en-US","publisher":{"@id":"https://onepageinvoice.com/#organization"},"url":"https://onepageinvoice.com/docs/api"}
```