Dates, time zones, currencies and API timestamps

Use library regional defaults for ordinary service formatting, an explicit display zone when the task requires it, and the receiving system's exact contract for API timestamps. Formatting a value does not convert its currency or change a stored date answer.

Regional defaults

Region settings supply library.profile.countryCode, locale, timeZone and currency. The Service time zone controls unzoned input, calendar arithmetic, current-day boundaries and Collection dates. Explicit expression arguments override the applicable default.

Display timestamps for people

{{ submittedAt | format_date }}
{{ submittedAt | date }}
{{ submittedAt | format_date: "dd/MM/yyyy HH:mm zzz", "Europe/London" }}
{{ submittedAt | date: "%Y-%m-%d %H:%M %Z", "Europe/London" }}

With no format, both filters show a labelled timestamp. Display-zone order is an explicit zone, then a valid viewer browser zone, then the deployed Service time zone, then Europe/London. A browser preference of UTC remains UTC. Background rendering has no browser zone and uses the Service time zone fallback.

Custom formats control exactly what is shown. Include zzz/XXX in a format_date time display or %Z/%z in date; a zone is not appended automatically. The token languages differ: format_date uses date-fns tokens, while date uses strftime tokens. Numeric input to date is seconds; format_date takes milliseconds.

Keep calendar dates as dates

{{ dateOfBirth | gfdate_to_string }}

A date answer such as a date of birth keeps its day, month and year. Use gfdate_to_string for YYYY-MM-DD where required. Only turn it into an instant if the destination requires an agreed midnight and time zone.

For example, parse_date: "yyyy-MM-dd HH:mm", "America/Toronto" interprets unzoned input there. Calendar-day calculations follow that zone's daylight-saving changes; a day is not always 24 elapsed hours.

Send an instant to an API

Choose the format required by the receiver. The following examples produce independent JSON values:

"submittedAt": {{ submittedAt | to_iso_string | to_json_string }}
"submittedAtMillis": {{ submittedAt | timestamp }}

to_iso_string returns UTC ISO 8601 text including milliseconds and Z. timestamp returns epoch milliseconds, not seconds. Both interpret unzoned input using the Service time zone unless explicitly supplied; to_iso_string's optional zone interprets its input, not its output zone. Use now for the current instant.

If the receiver requires a custom UTC format with three fractional digits, use:

{{ submittedAt | date: "%Y-%m-%dT%H:%M:%S.%LZ", "UTC" | to_json_string }}

A literal Z, or appending Z, only adds text; it does not convert a local time to UTC. Do not rely on a viewer's browser zone for outgoing machine timestamps.

Format numbers and currencies

{{ amount | format_number: 2, 2 }}
{{ amount | format_number: 2, 2, "fr-CA" }}
{{ amount | format_currency: true }}
{{ amount | format_currency: true, false, "en-CA", "CAD" }}

format_number takes minimum/maximum fraction digits and an optional locale, falling back to the library locale. format_currency takes include-fraction, rounding, optional locale and optional currency. Set its first argument to true to retain the fractional amount; the default false truncates it to a whole amount unless rounding is requested.

Currency formatting retains the existing two-decimal formatting behaviour for fractional amounts; it does not determine a payment provider's supported precision. It never converts GBP to CAD or changes merchant settings. Payment fee input uses major units; saved payment outcomes and account limits use ISO minor units. See Payment settings.

Check changes without rewriting history

Inspect the original value, existing expression, destination contract, zone and precision before changing an integration. Test winter/summer dates, daylight-saving boundaries, different browser zones and background rendering. Preserve stored answers and established API conventions. User view mocks do not prove real API acceptance; verify the authorised change in QA before deploying it.

See the full date/time/number filter reference and API action settings.