---
title: "Invoice templates"
description: "How to write, look at, validate, publish and promote the design of the printed invoice: the language, the functions, the data, the paper and what SUNAT requires."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.invox.page/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoice templates

A template says what the printed invoice looks like (the PDF in the email, the ticket at the till). You write it once; the service validates it against what SUNAT requires, stores it as a version that never changes and uses it for every invoice. Read this guide once, before you start.

## The whole path

| Step | Route | What happens |
| --- | --- | --- |
| 1. Create from a shared one | `POST /v1/templates` | With `from: "system:a4"` (or `system:thermal-80`, `system:thermal-58`) you start from a template that already passes validation. |
| 2. Edit the draft | `PUT /v1/templates/{id}/draft` | Send `source`, `manifest` and the `revision` you read. Saving checks the syntax and renders a sample; if someone saved first, it answers a conflict and overwrites nothing. |
| 3. Look at it | `POST /v1/templates/{id}/render` | The draft rendered with a sample, as `html`, `png` or `pdf`. If you can see images, ask for `png` and check your work. |
| 4. Validate | `POST /v1/templates/{id}/validate` | Renders every official sample, prints it and checks what is VISIBLE on the paper. Answers every rule and the validated `revision`. |
| 5. Publish | `POST /v1/templates/{id}/publish` | With the validated `revision`: creates a version that never changes, and TEST invoices use it from then on. |
| 6. Promote | `POST /v1/templates/{id}/promote` | A person decides: LIVE invoices use the promoted version. Going back is promoting another one. |

For a person to look or edit without signing in, create a link with `POST /v1/templates/{id}/preview_links` (scope `view`, `edit` or `publish`). From the command line, `invoicing templates pull | push | watch | validate | publish | promote | render` does the same with two files in a folder. To print with that design, send `template_id` when issuing, or set it as the issuer's `default_template` with `PUT /v1/issuer`. An organization has up to 20 active templates.

## The language

Liquid over HTML and CSS, with rules made for a template written by a third party:

- Everything you write with `{{ }}` is escaped. There is no `raw`.
- A field or a function that does not exist is an error with line, column and a suggestion ("Did you mean…?"), not a silent blank. A condition on a missing field is simply false.
- There is no `include`, `render` or `layout`: everything goes in one template.
- No JavaScript and no network when printing: what is not inside the document does not exist. Images come from your library and fonts from the catalog, both embedded.

The limits count steps, not time:

| Limit | Value |
| --- | --- |
| Length of the template | 200 000 characters |
| Steps while rendering (one per node and per turn of a loop) | 100 000 |
| Writes | 50 000 |
| Size of the rendered document, images included | 4 MB |

An A4 with 60 lines uses about 2 000 steps. Going over a limit answers [`template_limit_exceeded`](/errors/#template_limit_exceeded) and says which one.

## The functions

| Function | What for | Example |
| --- | --- | --- |
| `money` | Dinero con el símbolo de la moneda del documento; `money: false` sin símbolo. | `{{ invoice.totals.total \| money }}` → `S/ 1,593.00` |
| `quantity` | Una cantidad sin ceros de más. | `{{ item.quantity \| quantity }}` → `2` |
| `percent` | Un porcentaje. | `{{ tax.rate \| percent }}` → `18 %` |
| `date` | Fecha u hora de Lima, por su texto. Formato opcional (dd, MM, MMMM, yyyy, HH, mm, ss). | `{{ document.issued_at \| date: "dd/MM/yyyy HH:mm" }}` → `17/11/2026 10:30` |
| `in_words` | Un monto en letras, en la moneda del documento. El del total ya viene en invoice.amount_in_words. | `{{ invoice.totals.total \| in_words }}` → `SON: MIL QUINIENTOS NOVENTA Y TRES CON 00/100 SOLES` |
| `pad` | Rellena con ceros a la izquierda. | `{{ document.number \| pad: 8 }}` → `00000123` |
| `qr` | Dibuja el código QR (nivel Q, como pide SUNAT), sin red. Tamaño en píxeles CSS (96 = 25,4 mm). | `{{ document.qr_content \| qr: 96 }}` |
| `barcode` | Code 128 o EAN-13. Alto opcional en milímetros. | `{{ document.full_number \| barcode: "code128", 10 }}` |
| `asset` | Una imagen de la biblioteca de la organización, incrustada. | `<img src="{{ brand.images.logo \| asset }}">` |
| `font_family` | La familia de una fuente del catálogo, para CSS, con su respaldo. | `font-family: {{ brand.fonts.body \| font_family: "inter" }};` |
| `color` | Un color hexadecimal seguro para CSS, o el de respaldo. | `color: {{ brand.colors.primary \| color: "#16181d" }};` |
| `gt_zero` | Verdadero si un monto es mayor que cero. | `{% assign show = invoice.totals.exempt \| gt_zero %}{% if show %}…{% endif %}` |
| `upcase · downcase · truncate` | Texto en mayúsculas, minúsculas o recortado (de Liquid). | `{{ document.customer.name \| truncate: 40 }}` |

## The print data

Your template receives a JSON with four keys: `version`, `document` (the common data: issuer, establishment, customer, series and number, date, QR, marks, labels), `invoice` (items, taxes, discounts, totals, amount in words, payment and instalments, legends) and `brand` (the organization's brand). Every key is ALWAYS present: what is missing is `null`, an empty list is `[]`. Money comes as text with two decimals. The full schema is at `GET /v1/print_data/schema` and the official samples at `GET /v1/print_data/samples`.

| Field | What it is |
| --- | --- |
| `document.type_label`, `document.full_number` | "Factura electrónica", "F001-00000123" |
| `document.issued_at` | Lima date and time, with no zone (use `date`) |
| `document.issuer.legal_name`, `.trade_name`, `.tax_id`, `.address.full` | The issuer as it was when the invoice was issued |
| `document.establishment.code`, `.name`, `.address.full` | The establishment it was issued from (`null` on older invoices) |
| `document.customer.name`, `.id_type_label`, `.id_number` | The customer |
| `document.qr_content` | The text of the QR: draw it with `qr` |
| `document.marks` | "SIN VALOR FISCAL", "ANULADO": loop over them and show them all |
| `document.labels` | The fixed labels ("RUC", "Total"…) and `printed_representation` |
| `invoice.items[]` | `quantity`, `unit_label`, `description`, `unit_price`, `value`, `total` |
| `invoice.totals` | `taxable`, `exempt`, `unaffected`, `taxes`, `subtotal`, `total`… |
| `invoice.amount_in_words` | "SON: … SOLES", the same text as in the signed XML |
| `invoice.payment` | Cash or credit, with its instalments |
| `invoice.legends[]` | The SUNAT legends (Amazonía, free transfer…) |

The official samples it is validated with:

| Sample | Name | What it tests |
| --- | --- | --- |
| `boleta_cash` | Boleta al contado | Una venta de mostrador sin cliente identificado, desde un local anexo. |
| `boleta_customer` | Boleta con cliente | Una boleta de más de S/ 700 con cliente identificado por DNI: el cliente debe verse. |
| `factura_discounts` | Factura con descuentos | Descuento por ítem, descuento global que afecta la base y otro que no la afecta, y un ítem exonerado. |
| `factura_credit` | Factura a crédito | Pago a crédito en tres cuotas con descuento global del 10 %. |
| `many_lines` | Muchas líneas | Sesenta ítems: la tabla debe continuar en varias páginas sin perder filas ni totales. |
| `long_names` | Nombres muy largos | Razón social, cliente, dirección y descripción largas: nada debe salirse del papel ni cortarse. |
| `voided` | Anulada | Una factura anulada: la marca «ANULADO» debe verse. |
| `test` | De prueba | Una boleta emitida en Pruebas: la marca «SIN VALOR FISCAL» debe verse. |
| `boleta_icbper` | Boleta con ICBPER | Una bolsa plástica: el impuesto a las bolsas (ICBPER) debe verse. |
| `credit_note` | Nota de crédito | La devolución de un monitor: el documento que modifica y el motivo deben verse. |
| `debit_note` | Nota de débito | Intereses por pago tardío de una factura: el documento que modifica y el motivo deben verse. |

## The brand and the images

`brand` carries the organization's values, never a design: `brand.colors` (`primary`, `accent`, `text`, `muted`…), `brand.fonts` (`heading`, `body`, `mono`), `brand.images` (`logo`, `logo_mono`: names in the library) and `brand.texts` (`header`, `footer`). They are edited with `PUT /v1/brand`; every invoice keeps the brand it had when it was issued. Using or ignoring them is up to your template.

Images live in the organization's library: upload them with `PUT /v1/assets/{name}` (PNG, JPEG, WebP or sanitized SVG, up to 512 KB) and use them by name: `{{ 'logo' | asset }}` or `{{ brand.images.logo | asset }}`. On publishing, the version keeps the exact fingerprint of every image it used: changing the image later does not change what was published. A name that is not in the library answers [`asset_not_found`](/errors/#asset_not_found).

## The paper

The manifest declares it, not the CSS:

```json
{
  "paper": {
    "kind": "thermal_80"
  },
  "print_data_version": 1,
  "document_types": [
    "factura",
    "boleta"
  ],
  "fonts": [
    "geist-mono"
  ]
}
```

| `paper.kind` | Width | Height |
| --- | --- | --- |
| `a4` | 210 mm | 297 mm |
| `letter` | 215.9 mm | 279.4 mm |
| `thermal_80` | 80 mm | measured from the content (up to 4 000 mm per page; anything taller continues on another) |
| `thermal_58` | 58 mm | measured from the content (up to 4 000 mm per page; anything taller continues on another) |
| `custom` | `width_mm` (40 to 500) | `height_mm` (40 to 4 000), or `null` to measure it |

**Do not put `@page { size }` in your CSS**: the manifest decides the paper, and a rule that changes the sheet is rejected when printing. The margins of `@page` are respected.

## The fonts

Only those in the catalog (`GET /v1/fonts`), embedded when printing. Declare them in `manifest.fonts` or ask for them with `font_family`; one that is not in the catalog answers [`font_not_in_catalog`](/errors/#font_not_in_catalog).

| Font | Family | Kind |
| --- | --- | --- |
| `inter` | Inter | sans-serif |
| `ibm-plex-sans` | IBM Plex Sans | sans-serif |
| `source-serif-4` | Source Serif 4 | serif |
| `geist-mono` | Geist Mono | monospace |

## What printing for real taught us

- **One block per required field.** RUC, legal name, series and number, date and totals are looked for in the text left on the paper. Put each one in its own block (`<p>`, `<div>`): two fields stuck together on one line can be read as one.
- **Long names must wrap.** Use `overflow-wrap: anywhere` on descriptions and names: text that runs off the paper fails validation (`documento_desborde`).
- **No links.** The sanitizer removes every `href`, `script`, `iframe`, form and outside resource. Anything the sanitizer has to remove fails validation (`plantilla_saneado`): remove it from the template yourself.
- **Hidden does not count.** A required field with `display:none`, white on white or off the page is not on the paper, and validation fails.
- **The QR goes at the bottom, at its size.** Draw it with `qr` (a QR made any other way does not count), after the totals, at least as large as validation says.
- **Always the marks.** Loop over `document.marks`: a test or voided invoice must never look valid.

## A starting point

The shortest template that can pass validation for factura and boleta (the `system:*` templates are the complete example):

```liquid
<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <title>{{ document.type_label }} {{ document.full_number }}</title>
  <style>
    body { font-family: {{ brand.fonts.body | font_family: "geist-mono" }}; font-size: 8pt; margin: 3mm; }
    .linea { display: block; margin: 0 0 1mm; overflow-wrap: anywhere; }
  </style>
</head>
<body>
  {% for mark in document.marks %}<p class="linea"><strong>{{ mark.text }}</strong></p>{% endfor %}
  <p class="linea">{{ document.issuer.legal_name }}</p>
  {% if document.issuer.trade_name %}<p class="linea">{{ document.issuer.trade_name }}</p>{% endif %}
  <p class="linea">{{ document.labels.tax_id }} {{ document.issuer.tax_id }}</p>
  <p class="linea">{{ document.type_label }}</p>
  <p class="linea">{{ document.full_number }}</p>
  <p class="linea">{{ document.issued_at | date: "dd/MM/yyyy HH:mm" }}</p>
  <p class="linea">{{ document.currency.name }}</p>
  <p class="linea">{{ document.customer.id_type_label }} {{ document.customer.id_number }}</p>
  <p class="linea">{{ document.customer.name }}</p>
  {% for item in invoice.items %}
  <div class="linea">
    <p class="linea">{{ item.description }}</p>
    <p class="linea">{{ item.quantity | quantity }} {{ item.unit_label | default: item.unit_code }} x {{ item.unit_price | money }}</p>
    <p class="linea">Valor unitario {{ item.unit_value | money }}</p>
    <p class="linea">Valor de venta {{ item.value | money }}</p>
    {% for tax in item.taxes %}<p class="linea">{{ tax.label }} {{ tax.amount | money }}</p>{% endfor %}
    <p class="linea">Importe {{ item.total | money }}</p>
  </div>
  {% endfor %}
  {% for adjustment in invoice.discounts %}<p class="linea">{{ adjustment.label }} {{ adjustment.amount | money }}</p>{% endfor %}
  {% for adjustment in invoice.charges %}<p class="linea">{{ adjustment.label }} {{ adjustment.amount | money }}</p>{% endfor %}
  <p class="linea">Op. gravadas {{ invoice.totals.taxable | money }}</p>
  <p class="linea">Op. exoneradas {{ invoice.totals.exempt | money }}</p>
  <p class="linea">Op. inafectas {{ invoice.totals.unaffected | money }}</p>
  <p class="linea">Valor de venta {{ invoice.totals.sale_value | money }}</p>
  <p class="linea">Descuentos {{ invoice.totals.discounts | money }}</p>
  {% for tax in invoice.taxes %}<p class="linea">{{ tax.label }} {{ tax.amount | money }}</p>{% endfor %}
  <p class="linea">Total {{ invoice.totals.total | money }}</p>
  <p class="linea">{{ invoice.amount_in_words }}</p>
  {% if document.qr_content %}{{ document.qr_content | qr: 120 }}{% endif %}
  <p class="linea">{{ document.labels.printed_representation }}</p>
</body>
</html>
```

## What validation checks

Every official sample your template accepts is rendered, printed with the real service and checked. A rule that fails blocks publishing; a warning does not. The answer says, per rule, in which sample it failed and how to fix it.

| Group | What it checks |
| --- | --- |
| `plantilla` | The manifest is valid, every sample renders within the limits and the sanitizer had nothing to remove. |
| `contenido_obligatorio` | What SUNAT requires on the printed representation, looked for in the VISIBLE text: 45 rules (below). |
| `codigo_qr` | `qr_presente`, `qr_nivel_q`, `qr_tamano`, `qr_parte_inferior`: the invoice's QR, level Q, on the paper, with modules of 0.19 mm or more and at the bottom. |
| `documento` | The marks are visible, nothing runs off the paper, nothing was requested from outside; the payment terms and the instalments (warning only). |

| Rule | What must be visible | Source |
| --- | --- | --- |
| `emisor_razon_social` | Razón social del emisor | A1 it. 3; A2 it. 3; A3/A4 it. 3 |
| `emisor_nombre_comercial` | Nombre comercial del emisor | A1 it. 4; A2 it. 4; A3/A4 it. 4 |
| `emisor_ruc` | RUC del emisor | A1 it. 6; A2 it. 6; A3/A4 it. 6 |
| `denominacion_documento` | Denominación del documento | A1 it. 7; A2 it. 7; A3/A4 it. 8 |
| `serie_numero` | Serie y número | A1 it. 8; A2 it. 8; A3/A4 it. 8 |
| `fecha_emision` | Fecha de emisión | A1 it. 1; A2 it. 1; A3/A4 it. 1 |
| `moneda` | Moneda del documento | A1 it. 9; A2 it. 9; A3/A4 it. 9 |
| `adquirente_documento` | Documento del cliente | A1 it. 11; A3/A4 it. 11 |
| `adquirente_nombre` | Nombre del cliente | A1 it. 12; A3/A4 it. 12 |
| `boleta_adquirente` | Cliente de la boleta | A2 it. 11 y 12; RCP art. 8 num. 3.10 (regla conservadora de 07 §5) |
| `item_descripcion` | Descripción de cada ítem | A1 it. 16; A2 it. 17; A3/A4 it. 18 |
| `item_cantidad` | Cantidad de cada ítem | A1 it. 15; A2 it. 16; A3/A4 it. 14 |
| `item_unidad` | Unidad de cada ítem | A1 it. 14; A2 it. 15; A3/A4 it. 13 |
| `item_precio_unitario` | Precio unitario por ítem | A1 it. 22; A2 it. 23; A3/A4 it. 21 |
| `item_valor_unitario` | Valor unitario por ítem | A3/A4 it. 19 |
| `boleta_item_valor_venta` | Valor y tributos por ítem | A2 it. 29 y 30 |
| `total_op_gravadas` | Total de operaciones gravadas | A1 it. 33; A2 it. 33; A3/A4 it. 28 |
| `total_op_inafectas` | Total de operaciones inafectas | A1 it. 34; A2 it. 34; A3/A4 it. 29 |
| `total_op_exoneradas` | Total de operaciones exoneradas | A1 it. 35; A2 it. 35; A3/A4 it. 30 |
| `total_op_exportacion` | Total de exportación | A1 it. 36; A2 it. 36; A3/A4 it. 31 |
| `total_op_gratuitas` | Total de operaciones gratuitas | A1 it. 37; A2 it. 37 |
| `total_igv` | Total del IGV | A1 it. 39; A3/A4 it. 34 |
| `total_isc` | Total del ISC | A1 it. 40; A3/A4 it. 35 |
| `total_otros_tributos` | Total de otros tributos | A1 it. 41; A3/A4 it. 36 |
| `total_icbper` | Total del ICBPER | A1 it. 40-A; A2 it. 40-A; A3/A4 it. 35-A |
| `total_otros_cargos` | Otros cargos | A1 it. 43; A3/A4 it. 37 |
| `total_otros_descuentos` | Otros descuentos | A1 it. 44; A2 it. 44 |
| `cargos_descuentos_globales` | Cargos y descuentos globales | A1 it. 45; A2 it. 45 |
| `boleta_total_valor_venta` | Valor de venta y subtotal | A2 it. 46 y 47 |
| `nota_total_tributos` | Tributos de la nota | A3/A4 it. 38 |
| `importe_total` | Importe total | A1 it. 48; A2 it. 48; A3/A4 it. 39 |
| `redondeo` | Redondeo del total | A1 it. 49 |
| `guia_relacionada` | Guía de remisión relacionada | A1 it. 59 |
| `documento_relacionado` | Documento relacionado | A1 it. 60; A2 it. 56; A4 it. 43 |
| `placa_vehiculo` | Placa del vehículo | A1 it. 63 |
| `direccion_itinerante` | Dirección de venta itinerante | A1 it. 64 |
| `leyendas_del_comprobante` | Leyendas del comprobante | A1 it. 61; A2 it. 57 |
| `leyenda_gratuita` | Leyenda de transferencia gratuita | A1 it. 61; A2 it. 57; catálogo 52 (1002) |
| `leyenda_amazonia` | Leyenda de la Amazonía | DS 103-99-EF art. 10; catálogo 52 (2001 a 2003) |
| `leyenda_detraccion` | Leyenda de detracción | RS 183-2004 art. 19.1 b); catálogo 52 (2006) |
| `leyenda_percepcion` | Leyenda de percepción | Catálogo 52 (2000) |
| `boleta_consolidada` | Boleta consolidada | A2 it. 17 |
| `nota_motivo` | Motivo de la nota | A3/A4 it. 10 |
| `nota_documento_modificado` | Documento que modifica la nota | A3/A4 it. 41 y 42 |
| `leyenda_representacion_impresa` | Leyenda de representación impresa | A1 it. 62; A2 it. 58; A3/A4 it. 45 |

## The errors and what to do

| Error | What to do |
| --- | --- |
| [`template_syntax_error`](/errors/#template_syntax_error) | Fix the line and column it gives; the answer carries a suggestion when there is an obvious one. |
| [`template_limit_exceeded`](/errors/#template_limit_exceeded) | Check the loops: one may never end, or may go over too much. |
| [`template_draft_conflict`](/errors/#template_draft_conflict) | Someone saved another revision: read again, merge and save with the current revision. |
| [`template_validation_failed`](/errors/#template_validation_failed) | The answer carries every rule that failed, in which sample and how to fix it. Fix it, validate and publish the new revision. |
| [`render_unavailable`](/errors/#render_unavailable) | The print service is not answering right now: retry. Nothing was published. |
| [`asset_not_found`](/errors/#asset_not_found) | Upload the image with that name, or use another one. |
| [`font_not_in_catalog`](/errors/#font_not_in_catalog) | Use a font from the catalog. |
| [`template_document_type_not_accepted`](/errors/#template_document_type_not_accepted) | Add the document type to the manifest's `document_types`, or issue with another template. |
| [`template_not_published`](/errors/#template_not_published) | The template has no published version: publish it before issuing with it in test mode. |
| [`template_version_not_promoted`](/errors/#template_version_not_promoted) | In production only a promoted version is printed: a person must approve and promote it. |
| [`template_is_default`](/errors/#template_is_default) | Set another default on the issuer before archiving it. |

Source: https://docs.invox.page/templates/index.mdx
