Date & Time

Manipulate date and time values

Overview

The Date & Time tool provides 7 date/time operations: getCurrentDate, addToDate, subtractFromDate, formatDate, roundDate, getTimeBetweenDates, and extractDate. Date handling is timezone-aware. Supports multiple input formats including ISO strings, Unix timestamps (seconds/milliseconds), and custom format strings.

Category: Core Nodes
Tool Name: date_time
Version: 1

Appearance: Icon: lucide-Calendar | Color: #408000

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool does not require any credentials.

Operations

Operation	Value	Description
Add to a Date	addToDate	Move a date forward by a number of time units
Extract Part of a Date	extractDate	Read a single component, such as the month, out of a date
Format a Date	formatDate	Render a date as a string in a chosen format
Get Current Date	getCurrentDate	Produce the current date and time
Get Time Between Dates	getTimeBetweenDates	Measure the gap between two dates
Round a Date	roundDate	Snap a date to the start or end of a unit
Subtract From a Date	subtractFromDate	Move a date backward by a number of time units

Parameters

Add to a Date (addToDate)

Parameter	Type	Required	Default	Description
Date (magnitude)	string	Yes	—	The date to add to. Accepts ISO strings, timestamps, or date expressions.
Time Unit	options	No	days	The time unit for the duration.
				Options: years, quarters, months, weeks, days, hours, minutes, seconds, milliseconds
Duration	number	No	0	The number of time units to add or subtract.
Output Field Name	string	No	newDate	Name of the output field.

Extract Part of a Date (extractDate)

Parameter	Type	Required	Default	Description
Date (date)	string	Yes	—	The date to extract from.
Part	options	No	month	The part of the date to extract.
				Options: year, month, week (ISO week number), day, hour, minute, second
Output Field Name	string	No	datePart	Name of the output field.

Format a Date (formatDate)

Parameter	Type	Required	Default	Description
Date (date)	string	Yes	—	The date to format.
Format	options	No	MM/dd/yyyy	The format to output the date in.
				Options: MM/dd/yyyy, yyyy/MM/dd, MMMM dd yyyy, MM-dd-yyyy, yyyy-MM-dd, X (Unix timestamp in seconds), x (Unix timestamp in milliseconds), custom
Custom Format	string	No	—	The custom Luxon format string. (shown when Format is custom)
Output Field Name	string	No	formattedDate	Name of the output field.

Get Current Date (getCurrentDate)

Parameter	Type	Required	Default	Description
Include Time	boolean	No	true	Whether to include the time in the output or just the date (midnight).
Output Field Name	string	No	currentDate	Name of the output field to put the date value in.

Get Time Between Dates (getTimeBetweenDates)

Parameter	Type	Required	Default	Description
Start Date	string	Yes	—	The start date.
End Date	string	Yes	—	The end date.
Units	multiOptions	No	["days"]	The units to calculate the difference in. Select more than one to split the gap across them.
				Options: years, months, weeks, days, hours, minutes, seconds, milliseconds
Output Field Name	string	No	timeDifference	Name of the output field.

Round a Date (roundDate)

Parameter	Type	Required	Default	Description
Date (date)	string	Yes	—	The date to round.
Mode	options	No	roundDown	Whether to round down (start of) or round up (end of + 1).
				Options: roundDown, roundUp
To Nearest	options	No	day	The unit to round down to. (shown when Mode is roundDown)
				Options: year, month, week, day, hour, minute, second
To	options	No	month	The unit to round up to. (shown when Mode is roundUp)
				Options: month (end of month)
Output Field Name	string	No	roundedDate	Name of the output field.

Subtract From a Date (subtractFromDate)

Parameter	Type	Required	Default	Description
Date (magnitude)	string	Yes	—	The date to subtract from.
Time Unit	options	No	days	The time unit for the duration.
				Options: years, quarters, months, weeks, days, hours, minutes, seconds, milliseconds
Duration	number	No	0	The number of time units to add or subtract.
Output Field Name	string	No	newDate	Name of the output field.

All Operations

Parameter	Type	Required	Default	Description
Options	collection	No	{}	Shared parsing and output settings.
— Include Input Fields	boolean	No	false	Whether to include all input fields in the output alongside the result.
— Timezone	string	No	—	The timezone to use. If not set, UTC is used.
— From Format	string	No	—	The Luxon format string of the input date (helps with parsing non-standard formats). (shown when Operation is formatDate)
— Output as ISO String	boolean	No	false	Whether to output the duration as an ISO 8601 duration string instead of an object. (shown when Operation is getTimeBetweenDates)
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

One output item per input item. Binary data is forwarded.

The output item starts empty. By default only the result field is present — the rest of the input JSON is dropped. Turn on Include Input Fields to copy the incoming fields through and add the result beside them. The result is written at Output Field Name, or at result if you clear that field.

Operation	Type of the result value
getCurrentDate	ISO 8601 string. With Include Time off, the time is midnight at the start of today.
addToDate, subtractFromDate	ISO 8601 string of the shifted date.
formatDate	String in the chosen Format. X and x give the Unix timestamp in seconds and milliseconds. An empty input date yields null rather than an error.
roundDate	ISO 8601 string. roundDown snaps to the start of To Nearest; roundUp moves to the start of the next To unit.
getTimeBetweenDates	An object with one key per selected unit, or an ISO 8601 duration string when Output as ISO String is on.
extractDate	A number — the requested component. week gives the ISO week number.

With Include Input Fields on, a getTimeBetweenDates result looks like this:

{
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2024-01-15T12:00:00Z",
  "timeDifference": {
    "days": 14,
    "hours": 12
  }
}

Reference the result downstream by expression, e.g. {{ $json.timeDifference.days }}.

Dates are read flexibly: ISO 8601 strings, Unix timestamps in seconds or milliseconds, and anything standard date parsing accepts. Set From Format when the input uses a layout that is ambiguous, such as dd/MM/yyyy. A value that cannot be parsed at all fails the item.

All operations work in UTC unless you set Timezone, which takes an IANA name such as America/New_York.

Usage Examples

• Format a date to MM/DD/YYYY
• Add 7 days to a date field
• Get time between two dates in hours
• Extract the month from a timestamp

Example Configuration

Get the current date and time in a specific timezone:

{
  "type": "date_time",
  "parameters": {
    "operation": "getCurrentDate",
    "includeTime": true,
    "outputFieldName": "currentDateTime",
    "options": {
      "includeInputFields": false,
      "timezone": "America/New_York"
    }
  }
}

Add seven days to a date, keeping the original fields:

{
  "type": "date_time",
  "parameters": {
    "operation": "addToDate",
    "magnitude": "2024-01-15T10:30:00Z",
    "timeUnit": "days",
    "duration": 7,
    "outputFieldName": "futureDate",
    "options": {
      "includeInputFields": true,
      "timezone": "UTC"
    }
  }
}

Format a date with a custom pattern:

{
  "type": "date_time",
  "parameters": {
    "operation": "formatDate",
    "date": "2024-01-15T10:30:00Z",
    "format": "custom",
    "customFormat": "yyyy-MM-dd HH:mm:ss",
    "outputFieldName": "formattedDate",
    "options": {
      "includeInputFields": false,
      "timezone": "America/Los_Angeles"
    }
  }
}

Round a timestamp down to the start of its day:

{
  "type": "date_time",
  "parameters": {
    "operation": "roundDate",
    "date": "2024-01-15T14:30:45Z",
    "mode": "roundDown",
    "toNearest": "day",
    "outputFieldName": "roundedDate"
  }
}

Measure a gap in days and hours:

{
  "type": "date_time",
  "parameters": {
    "operation": "getTimeBetweenDates",
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-01-15T12:00:00Z",
    "units": ["days", "hours"],
    "outputFieldName": "timeDifference",
    "options": {
      "includeInputFields": true,
      "timezone": "UTC"
    }
  }
}

Pull the month number out of a timestamp:

{
  "type": "date_time",
  "parameters": {
    "operation": "extractDate",
    "date": "2024-01-15T14:30:45Z",
    "part": "month",
    "outputFieldName": "monthValue",
    "options": {
      "includeInputFields": false
    }
  }
}

Format a date taken from the incoming item:

{
  "type": "date_time",
  "parameters": {
    "operation": "formatDate",
    "date": "{{ $json.timestamp }}",
    "format": "MM/dd/yyyy",
    "outputFieldName": "displayDate"
  }
}

Calculate an expiry six months out:

{
  "type": "date_time",
  "parameters": {
    "operation": "addToDate",
    "magnitude": "{{ $json.createdAt }}",
    "timeUnit": "months",
    "duration": 6,
    "outputFieldName": "expiresAt"
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Manipulate dates: format, add/subtract, compare, round, extract parts — uses Luxon for timezone-aware operations.

Common Patterns

• Basic date formatting — use formatDate with one of the predefined formats for common date representations.
• Date arithmetic — use addToDate or subtractFromDate for scheduling and expiration calculations.
• Timezone conversion — set Timezone in Options to render a UTC value in a local zone.
• Date range calculations — use getTimeBetweenDates with the units your report needs, such as hours and minutes.

Notes

• Turn Include Input Fields on whenever a downstream node still needs the rest of the item; otherwise the result field is all that survives.
• formatDate only applies Timezone when you set it — leave it empty to format the date exactly as parsed.