# Custom fields and templates

> Add your own fields such as PO number or cost code to documents and lines, group them in a template per document kind, and print them on the PDF.

Source: /help/en/settings/custom-fields

Custom fields hold information Alya Books does not have a standard field for: a purchase order number, a project phase, a cost code per line. A template decides which fields appear on which document kind.

## Define fields

1. Go to **Settings → Documents → Custom fields** (owners and admins).
2. Click **Field** and fill in:
- **Label** and **Label (Arabic)**. The **Key** is derived from the label (lowercase letters, digits, underscores) and is what integrations send as `metadata.<key>`. It cannot be changed after saving.
- **Type**: Text, Number, Date, Yes / no, or Choice list. For a choice list, enter the options one per line, optionally as `value | Label`.
- **Applies to**: **Whole document** or **Each line**.
- **Order**, **Required** and **Print on PDF**.
3. Click **Save**.

## Build a template

1. Click **Template**, enter a **Name** and choose the **Document kind**.
2. Tick the fields it should contain and leave **Active** on.
3. Click **Save**. Only one template per document kind can be active; activating another one deactivates the previous.

## Where the fields appear

- In the invoice and quote editor: a **Custom fields** section in the right panel for document fields, and a tag icon on each line for line fields.
- On incoming invoices: a **Custom fields** card when a template for incoming invoices is active.
- On the PDF: fields marked **Print on PDF** are printed (document-level fields only): on invoices, credit and debit notes and proformas with the invoice details, or in the Shipment panel of a Logistics design; on quotes and letters under "Additional information".
- In the API and webhooks as `metadata`.

## Good to know

- Required fields block saving until filled, in the app and through the API.
- Values can still be edited on issued (locked) invoices, because they do not change the tax content.
- Deleting a field removes it from templates; stored values on old documents are kept.
- Categories and cost centres are separate lists at the bottom of the same tab, meant for reporting rather than free-form data.

## Related

- [Document designs and text presets](/help/en/settings/designs-and-text-presets)
- [Saved views, filters and columns](/help/en/settings/saved-views-and-columns)