Skip to main content

Plain Invoices

A plain invoice is a PDF invoice for a seller in a country that has no e-invoice format: the United States and most of the world outside Europe. It carries the seller's own invoice number, the seller's own name for its tax ("Sales tax", "GST"), and no VAT fields. When no line carries tax, the page has no tax line at all.

It is not an e-invoice. No XML is made, nothing is sent over Peppol or reported to a tax authority, and none of the EN 16931 or Peppol rules is applied. It does not appear among your transactions and does not count against your plan's document allowance.

Who can use itโ€‹

A seller whose country has no e-invoice format GoRoute serves. A seller in the EU or EEA, the United Kingdom, Switzerland, Australia, New Zealand, Singapore, Japan, Malaysia, the United Arab Emirates, Oman, Nigeria, Mexico or Saudi Arabia is refused with PLAIN_INVOICE_NOT_OFFERED and uses POST /invoices, which creates that country's e-invoice.

The seller's country is the one on the invoice (seller.address.country), or your organisation's when the invoice leaves it out.

The callsโ€‹

CallWhat it doesScope
POST /api/v1/documents/plain-invoice/checkSays what would be refused, and the totals. Stores nothing.read
POST /api/v1/documents/plain-invoiceCreates the invoice.send
GET /api/v1/documents/{document_id}/pdfThe PDF, with your logo and brand colour.read
GET /api/v1/documents?kind=invoiceYour plain invoices, newest first.read
GET /api/v1/documents/{document_id}The stored record.read
DELETE /api/v1/documents/{document_id}Deletes it.send

Creating oneโ€‹

The body is the same Canonical Invoice Model that POST /invoices takes. Totals are always worked out from the lines, so you can leave totals out.

curl -X POST https://app.goroute.ai/peppol-api/api/v1/documents/plain-invoice \
-H "X-API-Key: $GOROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"document": {
"number": "INV-1042",
"issue_date": "2026-11-12",
"due_date": "2026-12-12",
"currency": "USD",
"seller": {"name": "Harbor Design LLC",
"address": {"street": "12 Dock St", "city": "Portland", "postal_code": "04101", "country": "US"}},
"buyer": {"name": "Maple Street Bakery",
"address": {"street": "8 Maple St", "city": "Burlington", "postal_code": "05401", "country": "US"}},
"lines": [{"description": "Logo design", "quantity": 1, "unit": "EA", "unit_price": 1200.00,
"tax_category": "standard", "tax_rate": 5.5}],
"payment": {"terms": "Net 30"}
},
"tax_label": "Sales tax"
}'
{
"document_id": "4f6c1c1e-6f0e-4b1f-9a1f-0f8f6f1d2a10",
"kind": "invoice",
"number": "INV-1042",
"issue_date": "2026-11-12",
"currency": "USD",
"total": "1266.00",
"replayed": false
}
FieldMeaning
documentThe invoice. number is required and is your own invoice number.
tax_labelWhat the tax is called on this invoice, up to 30 characters. Default: your organisation's setting, else "Sales tax" for the United States and "Tax" elsewhere.
noteFree text printed under the lines.
metadataYour own data, stored with the invoice and never printed.

For a line with no tax, send "tax_rate": 0 with "tax_category": "outside_scope".

The invoice numberโ€‹

number is unique within your organisation. Sending the same invoice again answers the stored one with 200 and "replayed": true, so a retry is safe. A different invoice under a number already used is refused with 409 and PLAIN_INVOICE_NUMBER_TAKEN.

The name of your taxโ€‹

Set it once for the organisation and leave tax_label out of each request:

curl -X PUT https://app.goroute.ai/peppol-api/api/v1/settings/company/pdf \
-H "X-API-Key: $GOROUTE_API_KEY" -H "Content-Type: application/json" \
-d '{"tax_label": "GST/HST"}'

GET /api/v1/settings/company/pdf reads it back. An empty string clears it. The name is kept with each invoice when it is created, so an invoice prints the same way later even if the setting changes.

Limitsโ€‹

On the Free plan you can create as many plain invoices in a calendar month as the plan's monthly invoice figure; the next one is refused with 402 and PLAIN_INVOICE_LIMIT_REACHED until the first of the next month. The paid plans have no monthly limit on plain invoices.

Refusalsโ€‹

Statuserror_codeMeaning
422PLAIN_INVOICE_INVALIDThe invoice cannot be issued. errors lists each finding with its code, field and message.
409PLAIN_INVOICE_NUMBER_TAKENAnother invoice of yours already carries this number. document_id names it.
402PLAIN_INVOICE_LIMIT_REACHEDThe Free plan's monthly figure is used.

The findings in errors:

codeMeaning
PLAIN_INVOICE_NOT_OFFEREDThe seller's country has an e-invoice format. Use POST /invoices.
PLAIN_SELLER_COUNTRY_REQUIREDNeither the invoice nor your organisation names the seller's country.
PLAIN_TAX_LABELThe tax name is not plain text: it contains <, > or a control character.

Refused before the findings are checkedโ€‹

Some mistakes are caught when the request is read, before the checks above run. Both POST /api/v1/documents/plain-invoice/check and POST /api/v1/documents/plain-invoice then answer 422 in the standard request-validation shape: there is no error_code and no errors list. Instead, detail is a list with one entry per problem. loc gives the path to the field, for example ["body", "document", "lines", 0, "quantity"], and msg says what is wrong.

These are the mistakes caught this way:

Part of the invoiceRefused when
numberIt is missing or empty. Spaces alone count as empty.
issue_dateIt is missing.
due_dateIt is before issue_date.
currencyIt is missing or not three upper-case letters, such as USD or CAD.
seller.name, buyer.nameIt is missing or empty.
linesThe list is missing or empty.
lines[n].descriptionIt is missing or empty.
lines[n].quantityIt is missing, or it is zero or less.
lines[n].unit_priceIt is missing, or it is below zero.
lines[n].tax_rateIt is below 0 or above 100.
tax_labelIt is longer than 30 characters.