Date Operators & Helpers

Beeceptor's template engine provides date manipulation operators to generate dynamic date-time values for API responses. The engine supports current time retrieval (now), parsing arbitrary date strings (dateParse), adding or subtracting durations (dateAdd), and calculating differences between two dates (dateDiff). Output formats include ISO, UTC, Unix timestamps, and custom patterns—the same shorthands used by now and faker date helpers.

now - current time

The now operator allows you to retrieve the current date and time. Additionally, you can customize the format of the date-time output by passing a shorthand format parameter.

Syntax	Description & Sample Output
{{now}}	Current date-time, in long format Thu Oct 10 2024 04:39:51 GMT+0000 (Coordinated Universal Time)
{{now 'utc'}}	Current date-time in UTC format 2024-10-10T04:39:51Z
{{now 'iso'}}	Current date-time in ISO format 2024-10-10T04:39:51.000+00:00

now - relative time

You can create custom date-time values relative to the current time by using additional parameters that specify the duration. For example, you can set the time to be 5 minutes in the future or 1 hour in the past. The duration can be defined in seconds, minutes, hours, days, months, or years, and it accepts both positive and negative whole numbers.

This feature is particularly useful when you need an API response that always returns a recent or dynamically adjusted date whenever the API is called. Below are some examples to help you get relative date-time values:

Syntax	Description & Sample Output
{{now '{minutes:5}' 'utc'}}	Date-time exactly 5 minutes in the future 2024-10-10T04:44:51Z
{{now '{months:-11, days:1}' 'iso'}}	Date-time exactly 11 months in the past 2023-11-11T04:39:51.000+00:00
{{now '{hours:-5, minutes:-30}' 'YYYYMMDD'}}	Date with timezone adjustments 20241009
{{now '{hours:3}' 'utc'}}	Date-time 3 hours in the future (in UTC) 2024-10-10T07:39:51Z
{{now '{days: 1, hours:10}' 'utc'}}	Date-time 1 day and 3 hours in the future (in UTC) 2024-10-10T07:39:51Z

Notes:

• The first parameter lets you adjust the relative time. It accepts either a string or an object, for example, {{now '{minutes:5}'}} and {{now (object minutes=5)}} are both valid. For more details on using objects, see the object documentation.
• The final parameter is optional and defines the output format. You can find formatting options in the date/time formatting.

Date Formatting

When working with mock APIs, you might need to generate date values in a particular format. Beeceptor supports a range of date formatting options, enabling you to customize both standard and non-standard date outputs to suit your requirements.

Examples

You can generate date values using the following syntax with for a variety of formats. Below are some common examples:

Use Case	Template's Syntax	Template's Output
Future Date in ISO Format	{{faker 'date.future' 'iso'}}	2024-03-22T14:12:53.789+00:00
Recent Date in UTC Format	{{faker 'date.recent' 'utc'}}	2024-10-03T10:22:45Z
Future Timestamp in Milliseconds	{{faker 'date.future' 'timestamp'}}	1734963456000
Past Date in US Format	{{faker 'date.past' 'us'}}	12/15/2021
Custom Date Format (ISO with Milliseconds)	{{faker 'date.past' 'YYYY-MM-DDTHH:mm:ss.SSSZ'}}	2022-04-10T05:32:21.456+00:00
Time Only in Custom Format	{{faker 'date.past' 'HH:mm:ss.SSSZ'}}	11:45:32.123+00:00
Past Date in European Format	{{faker 'date.past' 'eu'}}	15/12/2021
Full Human-readable Date Format	{{faker 'date.past' 'full'}}	Wednesday, April 10, 2022 5:32:21 AM
Compact Date Format for Unique ID	{{faker 'date.past' 'compact'}}	20220410053221
SQL Compatible Format	{{faker 'date.past' 'sql'}}	2022-04-10 05:32:21

The examples above illustrate how to specify different formats using the faker function to meet your specific requirements.

Shorthand Syntax

Beeceptor supports several shorthand notations for date formatting. The table below shows these standard notations and their corresponding formats:

Shorthand	Format Specification	Description
iso	YYYY-MM-DDTHH:mm:ss.SSSZ	ISO 8601 format with milliseconds; useful for international standards.
iso8601	YYYY-MM-DDTHH:mm:ss.SSSZ	Another alias for ISO 8601, commonly used in APIs.
rfc2822	ddd, DD MMM YYYY HH:mm:ss ZZ	RFC 2822 format, often used for email headers.
rfc3339	YYYY-MM-DDTHH:mm:ssZ	RFC 3339 format, suitable for machine-readable timestamps.
w3c	YYYY-MM-DDTHH:mm:ssZ	W3C standard for date and time on the web.
unix	X	Unix epoch time in seconds, useful for Unix-based systems.
timestamp	x	Unix epoch time in milliseconds; great for precise timestamps.
short	YYYY-MM-DD	Short date format, ideal for compact displays of date only.
long	YYYY-MM-DD HH:mm:ss	Long format with time, typically used for detailed logs.
full	dddd, MMMM D, YYYY h:mm:ss A	Full, human-readable date format; great for user interfaces.
compact	YYYYMMDDHHmmss	Compact representation with no separators; useful for IDs.
utc	YYYY-MM-DD[T]HH:mm:ss[Z]	UTC format, recommended for data that needs universal reference.
sql	YYYY-MM-DD HH:mm:ss	SQL-compatible format for database entries.
us	MM/DD/YYYY	US date format, typically used in US-based applications.
eu	DD/MM/YYYY	European date format, commonly used across Europe.

dateAdd uses the same shorthand table for its optional output format parameter (defaults to iso when omitted).

dateParse Operator

Parses a date string or timestamp into a normalized date object that can be chained with other date operators such as dateAdd.

The operator automatically detects common date formats, including:

• ISO-8601
• RFC3339
• Unix timestamps (seconds)
• Unix timestamps (milliseconds)
• JavaScript date strings

Syntax

{{dateParse inputDate}}

Optional explicit input format:

{{dateParse inputDate inputFormat}}

Parameters

Parameter	Required	Description
inputDate	Yes	Date string, numeric timestamp, or value from request helpers (e.g. queryParam, body).
inputFormat	No	Explicit parse format. Use unix for seconds, timestamp for milliseconds, or a dayjs format string such as DD-MM-YYYY HH:mm:ss.

Supported Input Formats

Format	inputFormat value	Example input
ISO / RFC3339	(auto-detected)	2026-02-25T05:15:05Z
Unix (seconds)	unix	1740460505
Unix (milliseconds)	timestamp	1740460505000
Custom pattern	e.g. DD-MM-YYYY HH:mm:ss	25-02-2026 05:15:05

Examples

Parse ISO date (for chaining):

{{dateAdd (dateParse '2026-02-25T05:15:05Z') '{days:7}' 'utc'}}

Parse Unix timestamp:

{{dateParse 1740460505 'unix'}}

Parse millisecond timestamp:

{{dateParse 1740460505000 'timestamp'}}

Parse custom date format:

{{dateParse '25-02-2026 05:15:05' 'DD-MM-YYYY HH:mm:ss'}}

Notes

• dateParse returns an internal date object; it is not meant to be printed directly in a response.
• Chain the result with dateAdd, dateDiff, or future date operators.
• If parsing fails, Beeceptor returns a template evaluation error.

dateAdd Operator

Adds or subtracts a relative duration from an input date and returns the formatted result.

Syntax

{{dateAdd inputDate duration format}}

Parameters

Parameter	Required	Description
inputDate	Yes	Starting date (string, timestamp, parsed object from dateParse, or request value). Auto-parsed when possible.
duration	Yes	Relative offset as an object string (e.g. '{days:3}') or object helper syntax. Negative values subtract time.
format	No	Output format shorthand or custom pattern. Defaults to iso. Same options as now.

Supported Duration Units

milliseconds, seconds, minutes, hours, days, weeks, months, years (singular forms such as day and hour are also accepted).

Examples

Add 3 days:

{{dateAdd '2026-02-25T05:15:05Z' '{days:3}' 'iso'}}

Output:

2026-02-28T05:15:05.000+00:00

Subtract hours:

{{dateAdd '2026-02-25T05:15:05Z' '{hours:-5}' 'utc'}}

Output:

2026-02-25T00:15:05Z

Multiple units:

{{dateAdd '2026-02-25T05:15:05Z' '{days:1, hours:3}' 'utc'}}

Output:

2026-02-26T08:15:05Z

Using query parameters:

{
  "deliveryDate": "{{dateAdd (queryParam 'requestedDateTime') '{days:3}' 'iso'}}"
}

Request:

GET /orders?requestedDateTime=2026-02-25T05:15:05Z

Response:

{
  "deliveryDate": "2026-02-28T05:15:05.000+00:00"
}

Using a parsed date object:

{{dateAdd (dateParse (queryParam 'requestedDateTime')) '{days:7}' 'utc'}}

Unix timestamp output:

{{dateAdd 1740460505 '{days:7}' 'unix'}}

Output:

1741065305

Object helper duration syntax:

{{dateAdd '2026-02-25T05:15:05Z' (object days=3) 'iso'}}

Notes

• Input dates are auto-parsed when no explicit dateParse format is required.
• The format parameter is optional and defaults to iso.
• Supports both string durations and object helper syntax: {{dateAdd date (object days=3) 'iso'}}.

dateDiff Operator

Calculates the difference between two dates in the specified unit. Both dates are automatically parsed before comparison.

Syntax

{{dateDiff startDate endDate unit}}

Parameters

Parameter	Required	Description
startDate	Yes	Earlier reference date (string, timestamp, or request value).
endDate	Yes	Later reference date.
unit	Yes	Unit for the result (see supported units below).

Supported Units

milliseconds, seconds, minutes, hours, days, weeks, months, years

Examples

Difference in days:

{{dateDiff '2026-02-25T05:15:05Z' '2026-02-28T05:15:05Z' 'days'}}

Output:

3

Difference in hours:

{{dateDiff '2026-02-25T05:15:05Z' '2026-02-25T11:15:05Z' 'hours'}}

Output:

6

Compare request body dates:

{
  "processingDelay": {{dateDiff (body 'createdAt') (body 'processedAt') 'minutes'}}
}

SLA validation:

{{#if (lt (dateDiff (body 'createdAt') (body 'resolvedAt') 'hours') 24)}}
  true
{{else}}
  false
{{/if}}

Compare with current time:

{
  "expiresInDays": {{dateDiff (now) (body 'expiryDate') 'days'}}
}

Notes

• Returns a numeric value suitable for use inside JSON (no quotes around the helper in the template).
• Negative values are returned when endDate is earlier than startDate.
• If either date cannot be parsed, Beeceptor returns a template evaluation error.