# Placeholders

A **placeholder** is a named value your invoice template can insert: the recipient's name, the invoice reference, the total, or something you define yourself such as a purchase-order number.

Placeholders are what make one template work for every invoice: you write `#ph("recipient_name")` once, and each rendered PDF carries that invoice's own recipient.

They are used inside the two [Typst snippets](https://docs.uninvoice.app/templates/typst) you control: the post-invoice block and the footer.

## Reading a placeholder

```
Please quote #ph("payment_concept") when paying. 
```

`ph("key")` returns the value for that key, or an **empty string** if the invoice has no value for it. That makes optional content easy to guard, so a whole block disappears instead of leaving a stray label behind:

```
#if ph("purchase_order") != "" [ 
   *Purchase order:* #ph("purchase_order") 
 ] 
```

The `{{key}}` form

Older templates may contain `{{recipient_name}}` written directly in the text. That form still works (it is substituted before rendering) but it cannot express "leave this out when empty": an unfilled `{{key}}` leaves the literal text on the invoice. Prefer `#ph("key")`.

## Built-in placeholders

These are always available and are resolved from the invoice's own frozen data, so they show what was true when the invoice was created, never today's company or customer details. Dates and amounts are formatted in the invoice's language.

### The document

| Key                           | Value                                                                                                 |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| `invoice_id`                  | The document reference, for example `2026/0007` (a proforma or draft carries its own reference).      |
| `invoice_uuid`                | The internal identifier of the document.                                                              |
| `invoice_created_at`          | The document's date: the issue date for an issued invoice, the creation date for a proforma or draft. |
| `invoice_document_label`      | The document's name in its language: _Invoice_, _Corrective Invoice_, _Proforma_, _Draft Invoice_.    |
| `invoice_issue_label`         | The label for that date: _Issued_ for an issued invoice, _Created_ for a proforma or draft.           |
| `invoice_due`                 | The payment due date. Currently the same as `invoice_created_at`.                                     |
| `invoice_total`               | The total, formatted, without a currency, for example `1.234,56`.                                     |
| `invoice_total_with_currency` | The total followed by the currency code, for example `1.234,56 EUR`.                                  |
| `currency_code`               | The invoice's ISO-4217 currency code, for example `EUR`.                                              |

### Your company (the issuer)

| Key                            | Value                                                 |
| ------------------------------ | ----------------------------------------------------- |
| `company_name`                 | Legal name.                                           |
| `company_friendly_name`        | Trading / display name, if set.                       |
| `company_display_name`         | The friendly name when set, otherwise the legal name. |
| `company_email`                | Contact email.                                        |
| `company_phone`                | Contact phone.                                        |
| `company_fiscal_id`            | Tax identification number.                            |
| `company_address_lines`        | Street address, one line per line break.              |
| `company_address_lines_inline` | The same street address joined with commas.           |
| `company_address_zipcode`      | Postal code.                                          |
| `company_address_city`         | City.                                                 |
| `company_address_state`        | State / province.                                     |
| `company_address_country`      | Country name.                                         |

### The recipient

| Key                              | Value                                       |
| -------------------------------- | ------------------------------------------- |
| `recipient_name`                 | Name.                                       |
| `recipient_fiscal_id`            | Tax identification number.                  |
| `recipient_email`                | Contact email.                              |
| `recipient_phone`                | Contact phone.                              |
| `recipient_address_lines`        | Street address, one line per line break.    |
| `recipient_address_lines_inline` | The same street address joined with commas. |
| `recipient_address_zipcode`      | Postal code.                                |
| `recipient_address_city`         | City.                                       |
| `recipient_address_state`        | State / province.                           |
| `recipient_address_country`      | Country name.                               |

### Payment

| Key                 | Value                                              |
| ------------------- | -------------------------------------------------- |
| `payment_recipient` | Who to pay: your company's legal name.             |
| `payment_concept`   | What to quote when paying: the document reference. |

## Custom placeholders

When the value cannot be derived from the invoice (a purchase-order number, a billing period, a project code), you declare a **custom placeholder** and fill it in when creating the invoice.

A declaration has four parts:

| Field        | Meaning                                                             |
| ------------ | ------------------------------------------------------------------- |
| **Key**      | The name you read in the template, as in `#ph("purchase_order")`.   |
| **Label**    | What the person creating the invoice sees on the form. Required.    |
| **Required** | When on, the invoice cannot be created until the field has a value. |
| **Default**  | Pre-fills the field, and can still be edited per invoice.           |

A key cannot be one of the built-in keys listed above, and cannot be declared twice in the same place.

### Declaring a custom placeholder

- **Company-wide**: the **Invoice settings** card on the _Company_ page. Offered on every invoice.
- **Per recipient**: the **invoice template override** on a customer's entity form. Offered only on invoices to that customer.

When creating an invoice, the two sets are **merged**: the company's declarations plus the recipient's. If both declare the same key, the recipient's wins, so one customer can carry a different label, a different default, or a different required flag for the same key.

### Filling it in on an invoice

Once you pick a recipient on the invoice form, a field appears for each merged declaration, labelled as declared and pre-filled with its default. Required fields are validated before the invoice can be created.

![The Custom fields section of the invoice form, with one input per declared placeholder (a required Period and a Purchase order), each showing its key as the placeholder text.](https://docs.uninvoice.app/assets/images/invoice-custom-fields-e32ec204878013eba5437dae7f0ad58b.png)

The values are then **frozen onto that invoice**, alongside the template snippets themselves. Editing or removing a declaration later never changes an invoice that already exists, and an older invoice that predates a declaration simply resolves that key to an empty string, so a guarded block collapses instead of breaking.