> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dairo.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Print & delivery options
> Control how a letter is printed and posted — color, sides, address placement, delivery class, and payment slips.
Every letter carries two groups of options: how it is printed (`print`) and
how it travels (`delivery`). All of them are optional and all have defaults,
so a minimal create is already a valid letter.
## Print options
The `print` object controls the printing itself.
```json theme={null}
"print": {
"mode": "grayscale",
"sides": "duplex",
"addressPlacement": "left"
}
```
| Field | Values | When to change it |
| ------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode` | `grayscale` (default), `color` | `grayscale` is right for invoices, notices, and text-heavy documents. Use `color` for branded letterhead or anything where color carries meaning. |
| `sides` | `simplex` (default), `duplex` | `duplex` prints both sides of each sheet, so a longer document uses fewer sheets. |
| `addressPlacement` | `left` (default), `right` | Where the recipient address sits so it shows through the envelope window. Match it to your letterhead. |
## Delivery classes
The top-level `delivery` field sets the postal class.
| Value | What it is |
| ------------ | ---------------------------------------------------------------------------------------- |
| `economy` | The default — the standard class, the right pick for most mail. |
| `priority` | Expedited handling, where the destination offers it. |
| `registered` | Tracked delivery with delivery confirmation — for legal, contractual, and official mail. |
| `bulk` | A class for large, non-urgent mailings, where offered. |
| `premium` | The highest service tier, where offered. |
Not every delivery class is available for every destination. Price the exact
combination first with `POST /v1/letters/price` — it confirms the combination
and returns what it costs. See [Pricing](/letters/pricing).
## Set the options on a create
Print and delivery ride on the same create call:
```bash title="cURL" theme={null}
curl -X POST https://api.dairo.app/v1/letters \
-H "Authorization: Bearer $DAIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"pdfBase64": "JVBERi0xLjQK...",
"fileName": "contract.pdf",
"to": {
"name": "Jane Doe",
"street": "Hauptstrasse", "houseNumber": "12",
"postalCode": "8001", "city": "Zürich", "country": "CH"
},
"print": { "mode": "color", "sides": "duplex", "addressPlacement": "right" },
"delivery": "registered"
}'
```
```ts title="TypeScript" theme={null}
await dairo.letters.create({
pdfBase64: pdf.toString("base64"),
fileName: "contract.pdf",
to: {
name: "Jane Doe",
street: "Hauptstrasse",
houseNumber: "12",
postalCode: "8001",
city: "Zürich",
country: "CH",
},
print: { mode: "color", sides: "duplex", addressPlacement: "right" },
delivery: "registered",
});
```
```python title="Python" theme={null}
dairo.letters.create(
pdf_base64=base64.b64encode(pdf).decode(),
file_name="contract.pdf",
to={
"name": "Jane Doe",
"street": "Hauptstrasse",
"house_number": "12",
"postal_code": "8001",
"city": "Zürich",
"country": "CH",
},
print={"mode": "color", "sides": "duplex", "address_placement": "right"},
delivery="registered",
)
```
```bash title="CLI" theme={null}
dairo letter send --pdf ./contract.pdf \
--to-name "Jane Doe" --to-street "Hauptstrasse" --to-house-number 12 \
--to-postal-code 8001 --to-city "Zürich" --to-country CH \
--color --duplex --address-placement right \
--delivery registered --confirm
```
## Payment slips (QR-bill, SEPA)
Many European invoices ship with a payment slip — a region-standard, scannable
slip the recipient uses to pay. There are two ways to add one: have Dairo
generate the slip from a `payment` object, or bring your own slip already
drawn in the PDF and declare it with the `paymentSlip` flag.
| Scheme | Slip | Currency |
| -------- | ------------------------------------------------------ | -------- |
| `qr` | Swiss QR-bill | `CHF` |
| `sepaDe` | German SEPA payment slip with a GiroCode (EPC QR code) | `EUR` |
| `sepaAt` | Austrian SEPA payment slip with a GiroCode | `EUR` |
Match the scheme to the destination — `qr` for Switzerland, `sepaDe` for
Germany, `sepaAt` for Austria. A slip only carries meaning in the region whose
standard it follows.
### Generate the slip with a `payment` object
Pass a `payment` object — the scheme `type`, the payee as a `creditor` block,
and the `amount` — and Dairo renders a standards-compliant payment part
full-width at the bottom of the letter, then prints the sheet on the matching
stationery.
A generated `payment` slip is only available when Dairo renders the letter —
pair it with a `templateId`, not `pdfBase64` or `file`. Pairing `payment` with
an inline PDF fails with `400` ("Payment slips require a template"). For a PDF
that already draws its own slip, use the `paymentSlip` flag instead.
| Field | Required | Description |
| ------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | yes | `qr`, `sepaDe`, or `sepaAt`. |
| `creditor.name` | yes | Name of the account holder being paid. |
| `creditor.iban` | yes | The IBAN to pay. For a Swiss QR-bill with a QR reference, use the QR-IBAN. |
| `creditor.country` | yes | Creditor country (ISO 3166-1 alpha-2). |
| `amount` | yes | The amount to pay, as a number greater than 0 with at most two decimals (`248.50`, not a string). |
| `currency` | no | Defaults to the scheme's currency (`CHF` for `qr`, `EUR` for SEPA); when set it must match it. |
| `reference` | no | The structured payment reference — a Swiss QR/ISR reference for `qr`, or the remittance reference for SEPA. Encoded into the QR code so the recipient's reference is prefilled. |
| `message` | no | Free-text note shown on the slip (unstructured remittance information). |
| `creditor.bic`, `creditor.street`, `creditor.houseNumber`, `creditor.postalCode`, `creditor.city` | no | Optional extra creditor details. |
| `debtor` | no | Optional payer block (`name`, `street`, `houseNumber`, `postalCode`, `city`, `country`); defaults to the letter recipient. |
```bash title="cURL" theme={null}
curl -X POST https://api.dairo.app/v1/letters \
-H "Authorization: Bearer $DAIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"templateId": "ltpl_invoice",
"fileName": "invoice-2026-06-118.pdf",
"to": {
"name": "Jane Doe",
"street": "Hauptstrasse", "houseNumber": "12",
"postalCode": "8001", "city": "Zürich", "country": "CH"
},
"payment": {
"type": "qr",
"creditor": { "name": "Acme AG", "iban": "CH4431999123000889012", "country": "CH" },
"amount": 248.50,
"currency": "CHF",
"reference": "210000000003139471430009017"
}
}'
```
```ts title="TypeScript" theme={null}
await dairo.letters.create({
templateId: "ltpl_invoice",
fileName: "invoice-2026-06-118.pdf",
to: {
name: "Jane Doe",
street: "Hauptstrasse",
houseNumber: "12",
postalCode: "8001",
city: "Zürich",
country: "CH",
},
payment: {
type: "qr",
creditor: { name: "Acme AG", iban: "CH4431999123000889012", country: "CH" },
amount: 248.5,
currency: "CHF",
reference: "210000000003139471430009017",
},
});
```
```python title="Python" theme={null}
dairo.letters.create(
template_id="ltpl_invoice",
file_name="invoice-2026-06-118.pdf",
to={
"name": "Jane Doe",
"street": "Hauptstrasse",
"house_number": "12",
"postal_code": "8001",
"city": "Zürich",
"country": "CH",
},
payment={
"type": "qr",
"creditor": {"name": "Acme AG", "iban": "CH4431999123000889012", "country": "CH"},
"amount": 248.50,
"currency": "CHF",
"reference": "210000000003139471430009017",
},
)
```
A German SEPA slip is the same call with a different `payment` block — a
`sepaDe` type, a `EUR` amount, and a German IBAN:
```json title="payment (German SEPA)" theme={null}
"payment": {
"type": "sepaDe",
"creditor": { "name": "Acme GmbH", "iban": "DE89370400440532013000", "country": "DE" },
"amount": 129.00,
"currency": "EUR",
"reference": "Rechnung 2026-06"
}
```
### Bring your own slip with the `paymentSlip` flag
If your PDF already lays out the QR-bill or SEPA slip — say your invoicing
tool draws it exactly where you want — set `paymentSlip` to `qr`, `sepaDe`, or
`sepaAt` instead of passing a `payment` object. The flag generates nothing; it
declares the kind of slip your document already contains so the letter is
printed on the right stationery.
```json theme={null}
{
"pdfBase64": "JVBERi0xLjQK...",
"fileName": "invoice-2026-06.pdf",
"to": { "name": "Jane Doe", "street": "Hauptstrasse", "houseNumber": "12", "postalCode": "8001", "city": "Zürich", "country": "CH" },
"paymentSlip": "qr"
}
```
Use either `payment` or `paymentSlip`, not both — `payment` makes Dairo draw
the slip, `paymentSlip` declares one you drew yourself. Omit both for an
ordinary letter.
### Stationery on the returned letter
The returned letter reports its stationery in `paperTypes` — `standard` (the
default), `qr`, `sepa_de`, or `sepa_at` — and echoes the chosen slip as
`paymentSlip` (`qr`, `sepaDe`, `sepaAt`, or `null`), whether Dairo generated
the slip or you supplied your own. A price request accepts the same
`paperTypes` tokens so a quote can mirror the letter you plan to send.
## Next steps
* [Send a letter](/letters/sending-a-letter) — use these options in a full create call.
* [Letter templates](/letters/templates) — the render path that generated payment slips require.
* [Status & tracking](/letters/status-lifecycle) — follow the letter once it is posted.