Custom Invoice Fields

Custom Invoice Fields let you attach your own data to invoices and invoice templates — for example a Purchase Order number, a Project Code, or any other piece of information that is specific to your workflow. Once a custom field is defined, you can set its value on every invoice and invoice template, and use that value as a variable in mockups and invoice template fields. If you need fields that travel with the client across all their invoices, see the Custom Client Fields article.

What is a Custom Invoice Field

A Custom Invoice Field consists of two parts:

Values for a Custom Invoice Field are stored on every invoice and on every invoice template in your account. The values are optional — you can leave them empty on individual invoices or templates.

Managing Custom Invoice Field Definitions

Custom Invoice Fields are defined in Settings → Custom Invoice Fields. From there you can:

• Create a new field by entering its Key and Name.
• Rename an existing field.
• Delete a field.

Setting Values

Once a Custom Invoice Field is defined, the field appears in two places:

• In the invoice editor — you can set a value for each invoice individually.
• In the invoice template editor — you can set a value on the template itself. When the template is used to generate new invoices, the template’s value is copied to each generated invoice.

All Custom Invoice Field values are plain text. They are optional and can be left empty.

Using Custom Fields

Once a value is set, you can reference it as a variable in three places:

You don’t need to type these variables by hand — every Custom Invoice Field is automatically added to the variables picker in the mockup editor and in the invoice template editor, next to all built-in variables.

For example, to render the value of the po_number field, insert {{Invoice Custom Field: po_number}} into a mockup or template field. The variable will be replaced with the invoice’s actual value when the invoice is rendered to PDF, sent by email, or opened by the client through a public link.

If an invoice has no value set for the referenced field, the variable is replaced with an empty string.

Using Custom Fields in the Clerk API

Custom Invoice Field values are exposed on every invoice and invoice template in the Clerk API under the customFields object, keyed by the field’s Key. This makes Custom Invoice Fields a convenient place to store integration-specific data — for example an external system’s invoice ID, a CRM reference, or any other identifier you need to round-trip between Clerk and your own systems through the API.

Renaming a Custom Invoice Field Key

When you rename a field’s Key, the values already stored on invoices and invoice templates are preserved — the link between values and the field definition is internal and does not depend on the Key string.

However, variables that you have already inserted into mockups or invoice template fields are stored as plain text. They are not updated automatically. After renaming the Key, every occurrence of {{Invoice Custom Field: <old key>}} still points at the old Key and no longer matches any field — when the invoice is rendered, such a variable is left as is and appears as the literal token text. Update every occurrence manually to {{Invoice Custom Field: <new key>}} in your invoice mockups, time report mockups, and invoice templates.

Deleting a Custom Invoice Field

Deleting a Custom Invoice Field definition is irreversible and has two effects:

• All values stored for this field on invoices and invoice templates are permanently removed.
• Variables referencing the deleted field remain in mockups and invoice templates as plain text. When the invoice is rendered, they are left as is and appear as the literal token text. Remove them manually if you no longer need them.