Custom Client Fields

Custom Client Fields let you attach your own data to clients — for example a Cost Center, a Region, 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 client, and use that value as a variable in invoice mockups, time report mockups and invoice template fields. If you need fields that are set per invoice rather than per client, see the Custom Invoice Fields article.

What is a Custom Client Field

A Custom Client Field consists of two parts:

Values for a Custom Client Field are stored on every client in your account. The values are optional — you can leave them empty on individual clients.

Managing Custom Client Field Definitions

Custom Client Fields are defined in Settings → Custom Client 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 Client Field is defined, the field appears in the client editor. You can set a value for each client individually. When the client is selected on an invoice, that invoice’s rendering will pick up the client’s Custom Client Field values automatically.

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

Using Custom Fields

Once a value is set on a client, you can reference it as a variable in three places (every variable resolves to the value of the field on the invoice’s client):

You don’t need to type these variables by hand — every Custom Client 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 cost_center field, insert {{Client Custom Field: cost_center}} into a mockup or template field. The variable will be replaced with the value from the invoice’s client when the invoice is rendered to PDF, sent by email, or opened by the client through a public link.

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

Using Custom Fields in the Clerk API

Custom Client Field values are exposed on every client in the Clerk API under the customFields object, keyed by the field’s Key. This makes Custom Client Fields a convenient place to store integration-specific data — for example an external system’s client 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 Client Field Key

When you rename a field’s Key, the values already stored on clients 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 {{Client 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 {{Client Custom Field: <new key>}} in your invoice mockups, time report mockups, and invoice templates.

Deleting a Custom Client Field

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

• All values stored for this field on clients 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.