---
name: onepageinvoice
description: Create one-page invoices with the free onepageinvoice.com API — a shareable invoice page with a Pay button and a PDF, or just a PDF file. Use when the user asks to invoice or bill someone, or wants an invoice PDF.
---

# One Page Invoice

Make an invoice with `https://onepageinvoice.com`. No account or API key.
Full reference: https://onepageinvoice.com/docs/api.md (OpenAPI:
https://onepageinvoice.com/openapi.json).
If the `onepageinvoice` MCP tools (`create_invoice`, …) are connected, use
them instead of HTTP calls; the same rules apply.

## Steps

1. Collect what you need. Don't invent anything. **Required:**
   - invoice `number`: ask; if the user has none, suggest one (e.g. `2026-001`)
     and say so in your reply
   - `date` (default today) and `due_date` (e.g. date + 14 days)
   - sender `from.name`, client `to.name`
   - at least one line item: `description`, `quantity`, `unit_price`
     (a negative price is a discount)

   Optional: sender `from.address` (lines), `from.email`, `from.phone`,
   `from.tax_id`; client `to.lines` (attention and address lines — note the
   field is `lines`, not `address`) and `to.email`; `currency` (USD default;
   EUR, GBP, CAD, AUD, NZD, CHF, JPY); `tax_rate` (%; ask if VAT/sales tax
   applies); `payment_instructions` (up to 4 lines, e.g. bank details);
   `payment_url` (https link to Stripe, PayPal…: the Pay button); `notes` (up
   to 4 printed lines); `link` and `qr` (online invoices only: print the
   share page's address and/or a QR code to it; set both unless the user says
   otherwise); `page_size` (`letter` default, use `a4` outside the
   US and Canada); `template` (`classic`, `minimal`, `bold`).
2. Decide what to make:
   - **Online invoice** (when the user wants to send a link or be paid online):
     `POST /api/v1/invoices`. Returns a share page `url` for the client
     (invoice, PDF download, and a Pay button if there's a `payment_url`;
     bank details show with a copy button), `pdf_url`, and a private
     `edit_url` for the user.
   - **Just a PDF file**: `POST /api/v1/pdf` and save the response body as
     `invoice-<number>.pdf`. Nothing is stored.
   - To check an invoice without saving anything, `POST /api/v1/preview`:
     it returns `problems` (empty when it's ready) and `fits`.
3. Send the invoice as JSON:

   ```bash
   curl -sS https://onepageinvoice.com/api/v1/invoices \
     -H 'Content-Type: application/json' \
     -d '{
       "number": "2026-001", "date": "2026-11-05", "due_date": "2026-11-19",
       "currency": "EUR", "page_size": "a4",
       "from": {"name": "Ada Ferreira", "email": "ada@ferreira.studio",
                "address": ["Rua da Prata 14", "1100-413 Lisboa"]},
       "to": {"name": "Castelo Bakery Lda", "email": "joana@castelobakery.pt",
              "lines": ["Largo do Chiado 3", "1200-108 Lisboa"]},
       "items": [{"description": "Site survey and measurements", "quantity": 1, "unit_price": 450},
                 {"description": "Concept drawings, two options", "quantity": 2, "unit_price": 400}],
       "payment_instructions": ["Bank transfer: IBAN PT50 0002 0123 1234 5678 9015 4"],
       "link": true, "qr": true
     }'
   ```

   Add `"payment_url": "https://…"` only when the user gives you a real
   payment link.
4. On `422`, read `problems` (`field` + `message`), fix those fields (ask the
   user if needed) and retry. On `429`, wait `Retry-After` seconds.
5. Report back:
   - the share link (`url`) and the PDF (`pdf_url`) — open or show them;
   - the **edit link** (`edit_url`): private, lets the user review and change the
     invoice in the editor. Say it should not be shared.
   - Links expire 30 days after the last change.

## Rules

- You create a draft for the user to review. Don't say the invoice was sent:
  the user sends the link or PDF to their client.
- Never put amounts, client details or bank details in the invoice that the
  user didn't give you or confirm.
- Keep `edit_token` secret; use it only for `PUT`/`DELETE /api/v1/invoices/{id}`
  with `Authorization: Bearer <edit_token>` when the user asks to change or
  remove the invoice.
- Unknown JSON fields are rejected (400): check spelling against the reference.