# ADD\_TO\_DATETIME

The function ADD\_TO\_DATETIME adds a given number of years, months, weeks, days, hours, minutes, seconds, or milliseconds from a given DateTime.

This function takes three pieces of input: a [DateTime](../../variable-data-types/the-datetime-variable-data-type), a [Number](../../variable-data-types/the-number-variable-data-type), and a [string](../../variable-data-types/the-text-variable-data-type). The string designates which value in the given DateTime will be modified: "year", "month", "week", "day", "hour", "minute", "second," or "millisecond". This function adds the given Number from the designated value, and returns the resulting [DateTime](../../variable-data-types/the-datetime-variable-data-type).

#### Declaration

```javascript
ADD_TO_DATETIME(datetime, number, unit_string) -> datetime
```

&#x20;

#### Parameters

**datetime** (required, type: _DateTime_) Any valid DateTime.

**number** (required, type: &#x4E;_&#x75;mber_) The number of units to be added to one of the values in the given DateTime. This number can be negative; if given a negative number, ADD\_FROM\_DATETIME will add the negative number to the specified value in the DateTime, effectively performing a subtraction operation.

**unit\_string** (required, type: _string_) The units in the given DateTime that will be modified: "year", "month", "week", "day", "hour", "minute", "second," or "millisecond". In order to be correctly parsed by ADD\_TO\_DATETIME, the given string must exactly match one of the possible values given by [this table](../../airscript/working-with-dates-and-times/time-unit-values).

#### Return Values

**modified\_datetime** (type: _DateTime_) The DateTime that results from adding the given number of units to the given DateTime.

#### Examples

Assume all examples have access to the following DateTime object:

```javascript
example_date_and_time = {  
 "date": {  
  "day": 16,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 9,  
  "minute": 33,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}
```

The following example takes the date and time described in **example\_date\_and\_time** and adds 5 minutes to it. Not that the returned DateTime is identical to **example\_date\_and\_time**, save for the minute value:

```javascript
ADD_TO_DATETIME(example_date_and_time, 5, "minute") -> {  
 "date": {  
  "day": 16,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 9,  
  "minute": 38,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}
```

The following example takes the date and time described in **example\_date\_and\_time** and adds 20 hours to it. Note how this results in a change not only in the hour value of the resulting DateTime, but also in the the day:

```javascript
ADD_TO_DATETIME(example_date_and_time, 10, "hour") -> {  
 "date": {  
  "day": 17,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 5,  
  "minute": 33,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}
```

The following example takes the date and time described in **example\_date\_and\_time** and adds -1 day to it. Note how this effectively subtracts 1 to the given day value:

```javascript
ADD_TO_DATETIME(example_date_and_time, -1, "day") -> {  
 "date": {  
  "day": 15,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 9,  
  "minute": 33,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}
```

If ADD\_TO\_DATETIME is given a **unit\_string** it cannot parse, it simply returns the given DateTime unmodified, such as in the following example:

```javascript
ADD_TO_DATETIME(example_date_and_time, 33, "This is a string") -> {  
 "date": {  
  "day": 16,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 9,  
  "minute": 33,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}
```

&#x20;

#### Discussion

Adding negative values is the same as subtracting positive values, allowing ADD\_TO\_DATETIME to mimic the functionality of [SUBTRACT\_FROM\_DATETIME](subtract_from_datetime).

ADD\_TO\_DATETIME can be used in tandem with the [NOW](now) function in order to create a DateTime specifying a future date and time, which is particularly valuable in the context of [timers](../../actions/the-start-timer-action). For instance, to set an action to occur five minutes in the future, you can define the DateTime at which the action will occur as follows:

```javascript
ADD_TO_DATETIME(  
  NOW(),  
  5,  
  "minute"  
)
```
