Template format

A quick reference for writing your own .invoyatemplate file.

A template is a JSON file with the .invoyatemplate extension. It describes a layout and nothing else: which sections the invoice has, in what order, and how they look. Invoya fills in the details, and prints every label — Bill To, Total — in the language the app is set to.

The quickest start is a template from the gallery: download one, change it in any text editor, and open it in Invoya to see the result before you add it.

Format version

Showing what a template with "formatVersion": "1.3" can use. It works in Invoya 1.3 and later.

The file

The keys at the top level of the file.

Key	Value	What it does
`format`required	`"invoya.invoice-template"`	Marks the file as an Invoya template.
`formatVersion`required	`"1.3"`	The oldest version of Invoya the template works in, for example `"1.3"`. Older versions refuse the file. Use the version that introduced the newest key or block your template uses — the version picker above shows what each one has.
`id`required	`"…"`	A unique identifier, for example `com.yourname.paper`. Adding a template with an id you already have replaces your copy.
`name`required	`{ "en": "…", "de": "…", … }`	The name shown in the app, by language code: `en`, `de`, `ru`, `uk`. `en` is required, and is used for any language not listed.
`author`	`"…"`	Who made the template.
`page`	`{ … }`	Sheet size and margins. See below.
`style`	`{ … }`	Typeface, text size and colours. See below.
`letterhead`	`["business", …]`default: `[]`	The ids of the blocks that make up your letterhead. The app shows them as a preview in Business Info.
`blocks`required	`[ … ]`	The sections of the invoice, top to bottom. See below.

`page`

Sizes are in points: 1 pt is 1/72 of an inch, and an A4 sheet is 595 × 842 pt. The right margin is always the same as the left.

Key	Value	What it does
`size`	`"a4"`default: `"a4"`	The sheet. A4 is the only size for now.
`margins.top`	`72`default: `72`	Space above the first block.
`margins.left`	`72`default: `72`	Space on the left — and on the right.
`margins.bottom`	`72`default: `72`	Space below the last line before the content moves to the next page.
`margins.footer`	`30`default: `30`	Distance from the bottom of the sheet to the footer line.

`style`

Every key here is optional.

Key	Value	What it does
`bodySize`	`8.5`default: `8`	Text size in points.
`font`	`"sans" \| "serif" \| "mono" \| "rounded" \| "humanist"`default: `"sans"`	The typeface, by role: `sans` is Helvetica, `serif` Times New Roman, `mono` Courier, `rounded` Avenir Next, `humanist` Optima. All five are on every Mac, iPhone and iPad, so the invoice prints the same everywhere.
`accent`	`"#rrggbb"`default: `"#eff0f1"`	Colour of the filled title band and the table header.
`accentText`	`"#rrggbb"`default: `"#000000"`	Colour of text on the accent colour. A dark accent needs a light one.
`logoHeight`	`42`	Height of the logo when it sits beside your details. Without it, the logo is as tall as the details.

`blocks`

Blocks are drawn down the page in the order they are listed. Every block has a type, and may have an id — which only the letterhead list needs. A type can appear more than once, spacer especially.

`"type": "business"`

Your business details, as entered in Business Info, with your logo.

Key	Value	What it does
`align`	`"left" \| "center" \| "right"`default: `"right"`	Which side the details sit on.
`logo`	`"none" \| "left" \| "right" \| "above" \| "banner"`default: `"left"`	Where the logo goes. `left` and `right` put it beside the details, which works only on the side opposite them — on the same side it moves above them. `above` puts it on a line of its own above the details; `banner` is a larger, centred logo above everything.

`"type": "spacer"`

Empty space.

Key	Value	What it does
`height`required	`24`	In points.

`"type": "title"`

The word Invoice.

Key	Value	What it does
`align`	`"left" \| "center" \| "right"`default: `"center"`	Where it sits.
`filled`	`true \| false`default: `true`	Puts it on a band in the accent colour.

`"type": "invoiceMeta"`

The invoice number and dates.

Key	Value	What it does
`align`	`"left" \| "center" \| "right"`default: `"right"`	Which side they sit on.
`fields`	`["number", "invoiceDate", "dueDate"]`	Which lines to show, in this order.

`"type": "client"`

Who the invoice is addressed to.

Key	Value	What it does
`caption`	`"billTo"`	Adds a Bill To line above the client. Leave it out for no caption.

`"type": "items"`

The table of invoice lines — the only block that continues onto the next page when an invoice runs long.

Key	Value	What it does
`columns`	`["index", "description", "unit", "qty", "rate", "amount"]`	Which columns to show, in this order: line number, description, unit, quantity, rate, amount.
`borders`	`true \| false`default: `true`	Draws the table's lines.

`"type": "totals"`

The sums under the table.

Key	Value	What it does
`align`	`"left" \| "center" \| "right"`default: `"right"`	Which side they sit on.
`lines`	`["subtotal", "discount", "taxes", "total"]`	Which lines to show, in this order.

`"type": "terms"`

The contract's terms. Drawn only when the contract has some.

No options.

`"type": "payment"`

Your bank details.

Key	Value	What it does
`qr`	`"auto" \| "never"`default: `"auto"`	`auto` adds a SEPA payment QR code when the invoice is in euros, your IBAN is valid and Print QR on invoices in EUR is on. `never` leaves it out.

`"type": "footer"`

Printed at the foot of every page, wherever it sits in the list. Every template needs one that prints the footer text.

Key	Value	What it does
`left`	`"pageXofN"`	`pageXofN` prints Page 1 of 2 on the left — only when the invoice has more than one page.
`center`required	`"footerText"`	`footerText` prints the invoice's footer text in the middle: Created with Invoya app, or the user's own text from Settings → Invoice Template → Footer.

What the app refuses

A block type or a value that isn't on this page. Invoya refuses the whole file rather than print half an invoice.
A template without a footer block that has "center": "footerText". Every invoice prints its footer text, so a template has to make room for it.
A formatVersion newer than the app. Update Invoya and open the file again.
A file larger than 16 KB.

Good to know

Colours are written #rrggbb. A colour that can't be read prints as black.
A template can't carry fonts, images or text of its own: the typeface is one of the five above, the logo is the one set in the app, and every label comes from the app.

Example

Classic, the template every install starts with:

{
  "format": "invoya.invoice-template",
  "formatVersion": "1.3",
  "id": "app.invoya.classic",
  "name": {
    "en": "Classic",
    "de": "Klassisch",
    "ru": "Классический",
    "uk": "Класичний"
  },
  "author": "Invoya",
  "page": {
    "size": "a4",
    "margins": { "top": 72, "left": 72, "bottom": 72, "footer": 30 }
  },
  "style": { "bodySize": 8 },
  "letterhead": ["business"],
  "blocks": [
    { "id": "business", "type": "business", "align": "right", "logo": "left" },
    { "type": "spacer", "height": 30 },
    { "id": "title", "type": "title", "align": "center", "filled": true },
    { "id": "meta", "type": "invoiceMeta", "align": "right",
      "fields": ["number", "invoiceDate", "dueDate"] },
    { "id": "client", "type": "client", "caption": "billTo" },
    { "type": "spacer", "height": 30 },
    { "id": "items", "type": "items",
      "columns": ["index", "description", "unit", "qty", "rate", "amount"],
      "borders": true },
    { "type": "spacer", "height": 10 },
    { "id": "totals", "type": "totals", "align": "right",
      "lines": ["subtotal", "discount", "taxes", "total"] },
    { "id": "terms", "type": "terms" },
    { "id": "payment", "type": "payment", "qr": "auto" },
    { "id": "footer", "type": "footer", "left": "pageXofN", "center": "footerText" }
  ]
}

Send it to us

Made a template you like? Send the file to support@invoya.app and it may join the gallery.