> For the complete documentation index, see [llms.txt](https://docs.middle.app/middle-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.middle.app/middle-docs/product/accounts/workflow-parameters/dates-and-datetimes.md).

# Dates and Datetimes

These parameters work with dates, times, timestamps, and distances between dates. A Date has no time or timezone. A Time has no date. A Datetime combines a date and time, usually with a timezone offset.

The JSON examples below are complete parameter objects from the [workflow JSON format](https://docs.middle.app/middle-docs/product/accounts/workflow-parameters.md). `params` contains child parameters in the order shown. Date and time results are shown as ISO strings for readability; inside a workflow they are date and time values, not Text values.

## Date

JSON type: `date`.

A date value, entered with the date picker. `expression` holds the date in `YYYY-MM-DD` format. There are no child parameters.

```json
{
  "type": "date",
  "expression": "2026-10-07"
}
```

This returns the date `2026-10-07`. It does not represent midnight in a particular timezone. If a copied parameter includes a time and offset in its expression, Middle keeps the date portion as written; it does not convert the timestamp to another timezone first. An invalid date causes an error.

## Time

JSON type: `time`.

A time value, entered with the time picker. `expression` holds a 24-hour time such as `14:30:00`. There are no child parameters.

```json
{
  "type": "time",
  "expression": "14:30:00"
}
```

This returns the time `14:30:00`. It does not have a date. The picker stores hours, minutes, and seconds; the parser also accepts ISO times with fractional seconds or an offset. Use a time without an offset when combining it with a named timezone in Construct Datetime. An invalid time causes an error.

## Datetime

JSON type: `datetime`.

A timestamp with a date, time, and offset. `expression` holds the timestamp; there are no child parameters. Use `Z` or `+00:00` for UTC, or an explicit offset such as `-07:00`.

```json
{
  "type": "datetime",
  "expression": "2026-10-07T14:30:00-07:00"
}
```

This represents the same moment as `2026-10-07T21:30:00+00:00`. The offset in a copied workflow matters: `14:30:00-07:00` is not the same moment as `14:30:00+00:00`.

An expression without an offset produces a datetime without a timezone. It does not automatically mean UTC or the customer's local time. Include an offset when the value needs to identify a particular moment. An invalid expression causes an error.

## Construct Time

JSON type: `construct_time`.

Create a Time from a string supplied by another parameter. The first and only child is the time string, in 24-hour ISO format. The parent does not use `expression`.

```json
{
  "type": "construct_time",
  "params": [
    {
      "type": "template",
      "expression": "14:30:00"
    }
  ]
}
```

This returns the time `14:30:00`. Replace the Text child with a Variable Selector to read a time string from a record. At runtime, an existing Time value passes through and a null value stays null. Other value types and invalid time strings cause an error.

## Construct Datetime

JSON type: `construct_datetime`.

Combine three child parameters, in this order:

1. A Date.
2. A Time without a timezone offset.
3. Text containing the timezone name, such as `America/Los_Angeles` or `UTC`.

The parent does not use `expression`. The timezone says where the supplied date and time take place. It does not convert an existing timestamp from one timezone to another; use Convert Timezone of Datetime for that.

```json
{
  "type": "construct_datetime",
  "params": [
    {
      "type": "date",
      "expression": "2026-10-07"
    },
    {
      "type": "time",
      "expression": "14:30:00"
    },
    {
      "type": "template",
      "expression": "America/Los_Angeles"
    }
  ]
}
```

This returns `2026-10-07T14:30:00-07:00`. The named timezone determines the offset for that date, including daylight saving time. Missing or null components, the wrong value types, and unknown timezone names cause an error.

During a daylight saving change, some local times occur twice or do not occur at all. The current constructor uses the [timezone library's default](https://pythonhosted.org/pytz/#problems-with-localtime) (`is_dst=False`) and does not reject these local times. If the exact instant matters, use a Datetime with an explicit offset.

## Timedelta

JSON type: `construct_timedelta`.

Create a distance between dates or datetimes. `expression` selects the unit, and the first and only child supplies the number of units. The result is a Timedelta, not a number of seconds and not a timestamp.

| `expression`   | Unit                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------- |
| `microseconds` | One millionth of a second                                                                         |
| `milliseconds` | Listed in the editor, but currently fails; use `microseconds` with the amount multiplied by 1,000 |
| `seconds`      | Seconds                                                                                           |
| `minutes`      | Minutes                                                                                           |
| `hours`        | Hours                                                                                             |
| `days`         | Days                                                                                              |
| `weeks`        | Seven-day periods                                                                                 |
| `months`       | Calendar months                                                                                   |

```json
{
  "type": "construct_timedelta",
  "expression": "days",
  "params": [
    {
      "type": "math_expression",
      "expression": "7"
    }
  ]
}
```

This returns a seven-day Timedelta. Amounts can be negative. Middle converts the amount to an integer, so `1.9` becomes `1`, not one and nine tenths of a unit. Use a smaller unit when you need a fractional duration. Null amounts and unrecognized units cause an error.

### Adding or subtracting time

Insert a Timedelta into a [Number](https://docs.middle.app/middle-docs/product/accounts/workflow-parameters/constants-and-calculated-values.md#number) parameter to add or subtract it from a Date or Datetime. The following returns the date `2026-10-14`:

```json
{
  "type": "math_expression",
  "expression": "{} + {}",
  "params": [
    {
      "type": "date",
      "expression": "2026-10-07"
    },
    {
      "type": "construct_timedelta",
      "expression": "days",
      "params": [
        {
          "type": "math_expression",
          "expression": "7"
        }
      ]
    }
  ]
}
```

Change `+` to `-` to subtract the seven days. Calendar months are not fixed durations: adding one month to January 31 reaches the last day of February. Middle uses [calendar-aware date arithmetic](https://dateutil.readthedocs.io/en/stable/relativedelta.html) for these values.

## Format Date or Date Time

JSON type: `strftime`.

Convert a Date or Datetime to Text. The first child is the format string; the second is the Date or Datetime to format. The parent does not use `expression`.

```json
{
  "type": "strftime",
  "params": [
    {
      "type": "template",
      "expression": "%Y-%m-%d %H:%M:%S %z"
    },
    {
      "type": "datetime",
      "expression": "2026-10-07T14:30:00-07:00"
    }
  ]
}
```

This returns the string `2026-10-07 14:30:00 -0700`. Formatting uses the value's existing date, time, and offset. It does not convert timezones. Convert the timezone first if you want the result in another timezone.

A Date is formatted at midnight, with no timezone. A Time alone is not accepted here. Missing children, null values, and the wrong value types cause an error.

### Format codes

These codes are used by both Format Date or Date Time and Create Date Time from String. Other characters, such as `-`, `/`, `:`, and spaces, are literal text.

| Code        | Meaning                   | Example             |
| ----------- | ------------------------- | ------------------- |
| `%Y`        | Four-digit year           | `2026`              |
| `%y`        | Two-digit year            | `26`                |
| `%m`        | Month number              | `10`                |
| `%d`        | Day of month              | `07`                |
| `%H`        | Hour, 24-hour clock       | `14`                |
| `%I`        | Hour, 12-hour clock       | `02`                |
| `%p`        | AM or PM                  | `PM`                |
| `%M`        | Minute                    | `30`                |
| `%S`        | Second                    | `00`                |
| `%f`        | Microseconds              | `123456`            |
| `%z`        | UTC offset                | `-0700`             |
| `%Z`        | Timezone abbreviation     | `UTC`               |
| `%a` / `%A` | Short / full weekday name | `Wed` / `Wednesday` |
| `%b` / `%B` | Short / full month name   | `Oct` / `October`   |
| `%%`        | Literal percent sign      | `%`                 |

Names and AM/PM depend on the server's locale. `%Z` is not a general parser for names such as `America/Los_Angeles`; use `%z` to parse a numeric offset. See Python's [complete format-code reference](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes) for the remaining codes and parsing rules.

## Create Date Time from String

JSON type: `strptime`.

Convert Text into a Datetime using an explicit format. The first child is the format string; the second is the text to parse. The parent does not use `expression`. The text must match the format, including separators and any offset.

```json
{
  "type": "strptime",
  "params": [
    {
      "type": "template",
      "expression": "%m/%d/%Y %H:%M:%S %z"
    },
    {
      "type": "template",
      "expression": "10/07/2026 14:30:00 -0700"
    }
  ]
}
```

This returns `2026-10-07T14:30:00-07:00`. Replace the second child with a Variable Selector to parse a string from a record.

The result is always a Datetime, even when the format contains only a date. A date-only format produces midnight. Without `%z`, the result generally has no timezone; it does not automatically use your browser's timezone. Parsing `%Z` does not by itself attach a timezone. Missing children, null values, invalid dates, and text that does not match the format cause an error.

## Convert Timezone of Datetime

JSON type: `convert_tz`.

Convert a Datetime to another timezone. The first child is the Datetime; the second is Text containing the destination timezone name. The parent does not use `expression`.

```json
{
  "type": "convert_tz",
  "params": [
    {
      "type": "datetime",
      "expression": "2026-10-07T21:30:00+00:00"
    },
    {
      "type": "template",
      "expression": "America/Los_Angeles"
    }
  ]
}
```

This returns `2026-10-07T14:30:00-07:00`. The instant stays the same; its displayed date, time, and offset can change.

Use a datetime that already has an offset. If it has no timezone, the conversion assumes the server's local timezone, which may not be the timezone of the original data. Use Construct Datetime to attach a known timezone to a separate date and time instead.

Timezone names must be supported by Middle's timezone library, such as `UTC`, `America/Los_Angeles`, `America/New_York`, or `Europe/London`. A Date or Time alone, a null value, or an unknown timezone causes an error.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.middle.app/middle-docs/product/accounts/workflow-parameters/dates-and-datetimes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
