Liquid reference

Templates use Liquid, rendered with LiquidJS 10. Liquid runs on a template's HTML, and on the html of POST /v1/pdf when the request has a data object. It does not run on CSS.

Basics

{{ … }} outputs a value, {% … %} runs a tag, and | applies a filter. The keys of your data object are the template's variables.

• A variable that does not exist outputs nothing, rather than failing.
• Only your data's own properties are visible to the template.
• These tags are available: if, elsif, else, unless, case, for (with forloop, limit, offset, reversed, break, continue), tablerow, assign, capture, increment, decrement, cycle, echo, liquid, raw and comment.
• Partials are not supported: include, render and layout fail with a template error. Keep everything in one template.

Standard filters

All of LiquidJS's standard filters work, for example upcase, capitalize, truncate, replace, split, join, size, first, last, sort, where, map, sum, plus, minus, times, divided_by, round, default and date. The LiquidJS filter reference documents them all. A filter name that does not exist is an error (when you save a template, or when the HTML is rendered), never a silent no-op.

CastPDF filters

Three filters format values for documents, using JavaScript's built-in internationalisation (Intl). Each takes an optional locale, a BCP 47 tag such as en-US, de-DE or fr-CH, defaulting to en-US.

money

{{ value | money: currency, locale }} formats an amount in a currency.

The value may be a number or a numeric string. The number of decimals follows the currency (two for USD and EUR, none for JPY, rounded). Note the default currency: write the currency explicitly when it is not the euro.

Some locales put a no-break space between the amount and the symbol (as in 1.234,50 €), which keeps them on the same line in the PDF.

number

{{ value | number: decimals, locale }} formats a number with grouping separators and a fixed number of decimals.

format_date

{{ value | format_date: style, time_zone, locale }} formats a date.

The value may be an ISO 8601 string (such as "2026-09-28" or "2026-09-28T10:00:00Z") or a number of milliseconds since 1970.

The last example shows why the time zone matters: 23:30 UTC on 28 September is already 29 September in Berlin.

A value that is not a number (for money and number) or not a date (for format_date), a malformed currency code or an unknown time zone fails the render with template_render_error.

Escaping

Output is HTML-escaped by default, so data such as <b> or & in a customer name cannot break or change your HTML. Use the raw filter to output HTML you trust, such as a formatted address you built yourself:

Sandbox limits

Templates run in an isolated sandbox with no access to files or the network. Each render has these limits:

Exceeding the time, memory or tag limit is a template_render_error. Checking a template when you save it has the same time limit. These limits apply to Liquid only; the PDF rendering that follows has its own limits.

Errors and line numbers

A template that cannot be parsed or rendered fails with 422 and the code template_render_error. When LiquidJS knows where the problem is, details gives the line and column in the template's HTML, counted from 1:

{
  "error": {
    "code": "template_render_error",
    "message": "Template error: undefined filter: moneyy",
    "docs_url": "https://castpdf.com/docs/errors#template_render_error",
    "details": { "line": 2, "column": 1 }
  }
}

The position usually points at the start of the {{ … }} or {% … %} that failed. Syntax errors and unknown filters are caught when you save a template, so they do not reach your production renders; errors that depend on the data (such as money on a value that is not a number) appear when a document is rendered.