Dates & time

penscript provides operators for creating, formatting, comparing, and manipulating dates. These are used for deadline calculations, age-based eligibility rules, contract expiration checks, and time-sensitive automations.

Date Creation: `:date`

Creates a date from a string or retrieves the current date/time.

{ ":date": "now" }
// Result: "2026-01-27T16:34:54.757Z"

{ ":date": "2000-11-20" }
// Result: "2000-11-20T00:00:00.000Z"

Strings in ISO 8601 format ("2024-01-15T00:00:00.000Z") and YYYY-MM-DD format ("2024-01-15") are automatically parsed as dates. The system variable {$today} is also available in inline expressions for the current date.

Date Formatting: `:format-date`

Formats a date according to a pattern string.

{
  ":format-date": { ":date": "now" },
  ":pattern": "Y"
}
// Result: "2026"

{
  ":format-date": { ":date": "now" },
  ":pattern": "Y-M-D"
}
// Result: "2026-01-27"

{
  ":format-date": { ":date": "now" },
  ":pattern": "D/M/Y"
}
// Result: "27/01/2026"

Pattern Characters

Character	Description
`Y`	Year, 4 digits
`y`	Year, 2–4 digits
`M`	Month, 2 digits (zero-padded)
`m`	Month, 1–2 digits
`D`	Day, 2 digits (zero-padded)
`d`	Day, 1–2 digits
`x`	Any non-digit separator

Inline Formatting with Pipes

For quick formatting inside strings, use the formatDdMmYyyy pipe:

"{$today | formatDdMmYyyy}"
// → "27/01/2026"

"{data.created_at | formatDdMmYyyy}"
// Scope: { "data": { "created_at": "2015-10-20" } }
// → "20/10/2015"

Date Comparison

Using `:cmp`

Combine :cmp with dates and the | age pipe for age-based conditions:

{
  ":if": [
    {
      ":cmp": "{data.birthdate | age}",
      ":gte": 18,
      ":lte": 65
    }
  ],
  ":then": "Eligible",
  ":else": "Not eligible"
}

All standard comparison modifiers work: :eq, :neq, :gt, :gte/:ge, :lt, :lte/:le.

Inline Date Comparisons

Simple date comparisons can be expressed directly inside strings:

{
  ":if": "{{ myDate > now }}",
  ":then": "Future date",
  ":else": "Past or current date"
}

Direct inline comparison patterns:

"{ my_date > $today }"
// → true if my_date is after today

"{ my_date == $today }"
// → equality check with today

"{ data.birthdate | age >= 18 }"
// → age check

"{ my_date > $today ? 'Future' : 'Past' }"
// → ternary

Combined conditions:

"{ my_date != $today | my_date < $today }"
// → true if my_date is not today or is in the past

Date Difference: `:diff`

Calculates the difference between two dates in a specified unit.

{
  ":diff": [
    "{data.date1}",
    "{data.date2}",
    {
      ":comparator": "day"
    }
  ]
}

// Scope: { "data": { "date1": "2024-01-01", "date2": "2024-02-04" } }
// Result: 34

Available Comparators

Comparator	Returns
`"day"`	Number of days between the dates
`"hour"`	Number of hours
`"minute"`	Number of minutes
`"second"`	Number of seconds

Age Calculation: `| age`

Calculates the age in years from a date value. Available as an inline pipe.

"{data.birthdate | age}"

// Scope: { "data": { "birthdate": "2007-01-01" } }
// Result: 18

Commonly combined with :cmp for eligibility rules:

{
  ":if": [
    { ":cmp": "{data.birthdate | age}", ":gte": 18 }
  ],
  ":then": "Adult",
  ":else": "Minor"
}

Date Arithmetic: `:sum` with Dates

Add or subtract time from dates using duration strings. Single duration:

{
  ":format-date": {
    ":sum": ["{$today}", "2d"]
  }
}
// Result: Current date + 2 days

Multiple durations combined:

{
  ":format-date": {
    ":sum": ["{$today}", "2d", "3d", "72h", "2y"]
  }
}
// Result: Current date + 2 days + 3 days + 72 hours + 2 years

Supported Duration Units

Unit	Example	Description
Days	`"2d"`, `"3d"`	Add days
Hours	`"72h"`	Add hours
Years	`"2y"`	Add years

Raw Numbers and Strings

Raw numbers are treated as milliseconds. Negative numbers subtract time.
Numeric strings (e.g., "+86400") are treated as seconds.

{
  ":format-date": {
    ":sum": [
      { ":date": "now" },
      -8640000000
    ],
    ":pattern": "D-M-Y"
  }
}
// Result: Current date minus 100 days

Building Deadlines

A common pattern — calculate a deadline and format it for display:

{
  ":format-date": {
    ":sum": ["{$today}", "30d"]
  },
  ":pattern": "D/M/Y"
}
// → "13/03/2026" (30 days from today)

Next Steps

Variables & scope

$today and inline pipes

Logic & comparisons

Date-based conditions with :cmp

Numbers & calculations

:sum for date arithmetic

How penscript works

Date examples in automations

Get Started

Workspace

Penbox Agent

Cases

Forms

Penscript

Date Creation: `:date`

Date Formatting: `:format-date`

Pattern Characters

Inline Formatting with Pipes

Date Comparison

Using `:cmp`

Inline Date Comparisons

Date Difference: `:diff`

Available Comparators

Age Calculation: `| age`

Date Arithmetic: `:sum` with Dates

Supported Duration Units

Raw Numbers and Strings

Building Deadlines

Next Steps

Variables & scope

Logic & comparisons

Numbers & calculations

How penscript works

​Date Creation: :date

​Date Formatting: :format-date

​Pattern Characters

​Inline Formatting with Pipes

​Date Comparison

​Using :cmp

​Inline Date Comparisons

​Date Difference: :diff

​Available Comparators

​Age Calculation: | age

​Date Arithmetic: :sum with Dates

​Supported Duration Units

​Raw Numbers and Strings

​Building Deadlines

​Next Steps

Variables & scope

Logic & comparisons

Numbers & calculations

How penscript works

Date Creation: `:date`

Date Formatting: `:format-date`

Pattern Characters

Inline Formatting with Pipes

Date Comparison

Using `:cmp`

Inline Date Comparisons

Date Difference: `:diff`

Available Comparators

Age Calculation: `| age`

Date Arithmetic: `:sum` with Dates

Supported Duration Units

Raw Numbers and Strings

Building Deadlines

Next Steps