---
title: "Convert Date"
url: "https://help.flows.world/en/article/convert-date"
language: "en"
last_updated: "2026-09-19T07:43:08.267Z"
---

# Convert Date

### Overview

**Convert Date** transforms dates between different formats and time representations. Use this stage to convert dates from various formats, including Unix timestamps, into the required output format. It can be used to convert between human-readable dates, ISO formats, Unix timestamps, and custom date formats within a flow.

![](https://cdn-assets.productfruits.com/47417571-62f6-47c1-b51c-67fcf8155b08)

\* Example flow demonstrating how **Convert Date** transforms a player registration date into a different date and time format and uses the converted value in the next stage.

**Note:** The variable names, values, criteria, and configuration used in this example are for demonstration purposes only.

**Where to find it:** *Actions > Transformers* in the stage library.

## Convert Date

**Where to find it:** *Actions > Transformers* in the stage library.

## Configuration

### Required Fields

| Field | Description | Example |
| --- | --- | --- |
| **Input Date (Original)** | Date value to convert (date string or Unix timestamp) | `2026-01-06`, `1735948800`, `{{dateField}}` |
| **Input Format (Format)** | How to interpret the input date (pattern or Unix type) | `yyyy-MM-dd`, `UNIXSECOND`, `MM/dd/yyyy` |
| **Output Name (Output)** | Variable name to store converted date | `variable`, `displayDate`, `timestamp` |
| **Output Format (OutputFormat)** | How to format the output date (pattern or Unix type) | `MM/dd/yyyy`, `UNIXSECOND`, `MMMM dd, yyyy` |

**Using functions in these fields:** Any value field above accepts `@` functions, for example `@NowSecond` for the current time or `@calc(...)` for a calculation. 

See [Flows Functions](https://help.flows.world/en/article/flows-functions) for the full list.

## Unix Timestamp Types

| Type | Description | Example |
| --- | --- | --- |
| **UNIXSECOND** | Unix timestamp in seconds | `1735948800` |
| **UNIXMILLI** | Unix timestamp in milliseconds | `1735948800000` |
| **UNIXMIN** | Unix timestamp in minutes | `28932480` |

## System Variables

Use these system variables in the **Input Date** field to work with current timestamps:

| Variable | Format Type | Use Case |
| --- | --- | --- |
| **@NowSecond** | UNIXSECOND | Current time with second precision |
| **@Now** | UNIXMIN | Current time with minute precision |
| **@UnixMillis** | UNIXMILLI | Current time with millisecond precision |

### System Variable Example

Input Date: @NowSecond Input Format: UNIXSECOND Output Format: yyyy-MM-dd HH:mm:ss Result: Converts current time to readable format

## Exit Points

| Exit | When |
| --- | --- |
| **Pass** | Date conversion completes successfully |

**Important:** this stage has only a Pass exit, no Error exit. If the input value does not match the Input Format (a text date that does not fit the pattern, or a non-numeric value set to a Unix type), the conversion cannot happen and **the whole flow run stops at this stage**. It does not pass through, and there is no error path to catch it. Always check or set the input into a known format before this stage (use Route Flow to validate, or Set Default to supply a fallback) so a bad value never reaches it.

## How It Works

When executed, the stage:

1.  **Parses input date** - Reads date using specified input format (Unix or pattern)
2.  **Converts to internal representation** - Creates date object with all components
3.  **Formats output** - Applies output format to produce result string
4.  **Stores result** - Saves formatted date to output variable

**Key behavior:** All operations use UTC timezone. Time components default to 00:00:00 if not specified in pattern.

## Java SimpleDateFormat Patterns

Date2 uses Java SimpleDateFormat patterns for custom date parsing and formatting. Use these pattern symbols to build custom date formats:

| Pattern | Component | Description | Examples |
| --- | --- | --- | --- |
| **G** | Era | Era designator | AD, BC |
| **y** | Year | Calendar year (default) | 1996, 96 |
| **Y** | Year | ISO week-based year | 2009, 09 |
| **M** | Month | Month in year | September, Sep, 09 |
| **w** | Week | Week in year | 27 |
| **W** | Week | Week in month | 2 |
| **D** | Day | Day in year | 189 |
| **d** | Day | Day in month | 10 |
| **F** | Day | Day of week in month | 2 |
| **E** | Day | Day name in week | Tuesday, Tue |
| **e** | Day | Day number of week (1 = Monday, 7 = Sunday) | 1 |
| **a** | Time | AM/PM marker | PM |
| **H** | Time | Hour in day (0–23) | 0 |
| **k** | Time | Hour in day (1–24) | 24 |
| **K** | Time | Hour in AM/PM (0–11) | 0 |
| **h** | Time | Hour in AM/PM (1–12) | 12 |
| **m** | Time | Minute in hour | 30 |
| **s** | Time | Second in minute | 55 |
| **S** | Time | Millisecond | 978 |
| **z** | Timezone | General timezone | PST, GMT-08:00 |
| **Z** | Timezone | RFC 822 timezone | \-0800 |
| **X** | Timezone | ISO 8601 timezone | \-08, -0800, -08:00 |

### Pattern Letter Count Rules

The number of pattern letters changes the output. Name-based fields (month `M`, weekday `E`) switch between the full name and the short name. Number-based fields use the letter count as the minimum number of digits (zero-padded).

**Month name** (September shown so the length difference is clear):

-   `MMMM` → "September" (full name)
-   `MMM` → "Sep" (short name)
-   `MM` → "09" (two-digit number, zero-padded)
-   `M` → "9" (number, no leading zero)

**Zero-padding on numbers:** a single letter gives no leading zero, a double letter pads to two digits.

-   `d` → "9"  ·  `dd` → "09" (day)
-   `yyyy` → "1996"  ·  `yy` → "96" (year)

**Match the input format to how the date is actually written.** A value like `9-9-2026` needs input format `d-M-yyyy`; a zero-padded value like `09-09-2026` matches `dd-MM-yyyy`. There is no optional-digit wildcard, so the input pattern and the real text have to line up.

## CRITICAL: Calendar Year vs ISO Week-Based Year

**THIS DISTINCTION IS CRITICAL AND COMMONLY MISUNDERSTOOD**

| Pattern | Type | Use For |
| --- | --- | --- |
| **y / yyyy** | Calendar year | 99% of use cases (January 1 → December 31) |
| **Y / YYYY** | ISO week-based year | ISO week dates only (use with w for week in year) |

### Why It Matters

ISO week-based year rules cause year boundaries to differ from calendar years:

-   29 December 2025 (Monday) belongs to **ISO Week 1 of 2026**
-   Using `YYYY` on this date produces "2026" (wrong for calendar year!)
-   Using `yyyy` on this date produces "2025" (correct for calendar year)

### Critical Rule

**ALWAYS use** `**yyyy**` **(calendar year), NOT** `**YYYY**`

Only use `YYYY` (ISO week-based year) together with `w` (week in year) for ISO week date formats like `YYYY-'W'ww`.

### Valid vs Invalid Usage

| Pattern | Valid? | Reason |
| --- | --- | --- |
| `yyyy-MM-dd` | ✓ Valid | Calendar year with calendar month |
| `YYYY-'W'ww` | ✓ Valid | ISO week-based year with week number |
| `YYYY-MM-dd` | ✗ Invalid | Mixing week-based year with calendar month |
| `YYYY` alone | ✗ Invalid | Week-based year without week number |

## Common Safe Pattern Combinations

Use these patterns for most date/time needs:

| Use Case | Pattern | Example Output |
| --- | --- | --- |
| **System date** | `yyyy-MM-dd` | 2026-01-21 |
| **System datetime** | `yyyy-MM-dd HH:mm:ss` | 2026-01-21 14:30:00 |
| **Display date** | `MMMM dd, yyyy` | January 21, 2026 |
| **US format** | `MM/dd/yyyy` | 01/21/2026 |
| **European format** | `dd/MM/yyyy` | 21/01/2026 |
| **ISO week format** | `YYYY-'W'ww` | 2026-W04 |
| **Time only (24h)** | `HH:mm:ss` | 14:30:00 |
| **Time only (12h)** | `hh:mm a` | 02:30 PM |

## Common Use Cases

### 1\. ISO to US Format

Convert webhook date from ISO to US format for display.

**Configuration:**

-   Input Date: `{{webhook.timestamp}}`
-   Input Format: `yyyy-MM-dd`
-   Output Name: `displayDate`
-   Output Format: `MM/dd/yyyy`

**Result:**

Input:  "2026-01-06" Output: {{displayDate}} = "01/06/2026"

### 2\. Unix Seconds to Readable Date

Convert API response Unix timestamp to readable format.

**Configuration:**

-   Input Date: `{{apiResponse.createdAt}}`
-   Input Format: `UNIXSECOND`
-   Output Name: `createdDate`
-   Output Format: `MMMM dd, yyyy HH:mm:ss`

**Result:**

Input:  "1735948800" Output: {{createdDate}} = "January 06, 2026 00:00:00"

### 3\. User Date to Unix Timestamp

Convert user-entered date to Unix timestamp for API storage.

**Configuration:**

-   Input Date: `{{userInput.date}}`
-   Input Format: `MM/dd/yyyy`
-   Output Name: `timestamp`
-   Output Format: `UNIXSECOND`

**Result:**

Input:  "01/06/2026" Output: {{timestamp}} = "1735948800"

## Best Practices

-   ✓ Use `yyyy` for calendar year (99% of use cases)
-   ✓ Use system variables (@NowSecond, @Now, @UnixMillis) for current timestamp
-   ✓ Match pattern to input - if input has time, include time in Format pattern
-   ✓ Test patterns first to verify expected output
-   ✓ Use UNIXSECOND for storage (timezone-independent, standard)
-   ✓ Escape special characters with quotes: `yyyy-MM-dd'T'HH:mm`
-   ✓ Remember Y/w relationship - if using Y (ISO week year), must also use w (week in year)

## Common Mistakes

| Mistake | Problem | Fix |
| --- | --- | --- |
| Using YYYY for calendar dates | Wrong year on week boundaries (2025-12-29 becomes 2026-12-29) | Use `yyyy` for calendar year, not `YYYY` |
| Mixing MM (month) with mm (minutes) | Pattern produces wrong output | Remember: `MM` = month, `mm` = minutes |
| Not zero-padding | Inconsistent date formats | Use `MM/dd/yyyy` not `M/d/yyyy` for consistent padding |
| Missing quotes for literals | Pattern parsing fails | Quote special characters: `yyyy-MM-dd'T'HH:mm:ss` |
| Omitting time in pattern | Parser fails when data includes time | If input has time, include time components in pattern |

## Troubleshooting

| Issue | Common Cause | Fix |
| --- | --- | --- |
| Flow run stops at this stage (parse failure) | Input Format doesn't match the actual input value, so the date can't be parsed and the run aborts (no Error exit) | Verify the pattern exactly matches the input structure (include time if present); validate the input with Route Flow before this stage |
| Wrong output format | OutputFormat pattern incorrect | Test pattern produces desired output, use built-in types for Unix |
| Timezone issues (date off by hours) | Unix timestamp treated as local instead of UTC | All conversions use UTC - manually adjust timezone offset if needed |
| Year is wrong | Used YYYY instead of yyyy | Use `yyyy` for calendar dates (not `YYYY`) |

## Do's and Don'ts

### Do:

-   ✓ Use `yyyy` for calendar year (unless explicitly implementing ISO week dates)
-   ✓ Include time components in pattern when input data includes time
-   ✓ Use UNIXSECOND for internal storage
-   ✓ Test patterns before deploying
-   ✓ Use system variables (@NowSecond, @Now, @UnixMillis) for current time

### Don't:

-   ✗ Use `YYYY` for calendar dates (causes wrong year on week boundaries)
-   ✗ Mix calendar and week-based patterns (don't use `YYYY-MM-dd`)
-   ✗ Mix MM/mm (remember: MM = month, mm = minutes)
-   ✗ Assume timezone handling (all operations are UTC)
-   ✗ Use `Y` without `w` (ISO week-based year must be paired with week number)

## Limitations

-   **UTC Only:** All Unix timestamp conversions assume UTC. No timezone-aware conversions.
-   **English Locale:** Date parsing uses English locale only. Month names must be English.
-   **Limited Time Precision:** Supports seconds, milliseconds, and minutes only - no microseconds.

## Related Stages

-   [**Set Default Value**](https://help.flows.world/en/article/set-default-value)**:** Set timestamp before conversion
-   [**Change Data**](https://help.flows.world/en/article/change-data)**:** Manipulate date strings before conversion
-   [**Route Flow**](https://help.flows.world/en/article/route-flow)**:** Conditional routing based on dates
-   [**Increment Number**](https://help.flows.world/en/article/increment-number)**:** Add time duration to timestamps