# Macros in data flows

This guide will help you understand and use these macros effectively.

Check out the [Coupler.io Macros Generator](https://docs.google.com/spreadsheets/d/1wo5tABHRf45NUx5hmmiaLucssjCQvZTXdBLvs1EN6ds/edit?gid=998250121#gid=998250121) to optimize your flow.

### What are Macros?  <a href="#id-1-what-are-macros-ngkqk" id="id-1-what-are-macros-ngkqk"></a>

Macros allow you to dynamically insert date or date-time values in your data flow’s settings, which can help automate repetitive tasks or handle custom ranges that aren’t available in the preset dropdowns.

{% hint style="warning" %}
Our macros are converted to date/date-time using [UTC+0 ](https://time.is/UTC)timezone so scheduling configuration and data timeframes must be planned accordingly.
{% endhint %}

<details>

<summary>Check the example</summary>

If the needed date-time value is not available among the options in the dropdown, you can manually specify it in these [cases](#where-to-use-macros-qvunj). You can instead type `{{macro}}` into the macro field, and the data flow will automatically interpolate it with your date-time value.

<div align="left"><figure><img src="/files/o5d2TszGamPgRcf5gcB3" alt="" width="375"><figcaption></figcaption></figure></div>

</details>

### Macro's syntax <a href="#macros-syntax-hvbkz" id="macros-syntax-hvbkz"></a>

The general syntax for macros is:

**`{{macro}}`**

### Supported date macros <a href="#supported-date-macros-vmphd" id="supported-date-macros-vmphd"></a>

The default date format is YYYY-MM-DD which corresponds to the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date standard

* `today`
* `yesterday`
* `tomorrow`
* `thisweekstart`
  * `this`  can be replaced with `last`  or `next`
  * `week`  can be replaced with `month`  or `quarter`  or `year`
  * `start`  can be replaced with `end`
* `weekago`
  * `week`  can be replaced with `month`  or `quarter`  or `year`
* `2weeksago`
* `2weeksfromnow`
  * `2`  can be replaced with any number up to 3 digits
  * `weeks`  can be replaced with `days`  or `months`  or `quarters`  or `years`<br>

{% hint style="success" %}
**Tip:** to get data dynamically starting at the *start/end* of some period, use the following custom macro format:

* `{{2monthsago.endof(month).format(YYYY-MM-DD)}}`
* `2` can be replaced with any number up to 3 digits
* `months` can be replaced with `days` or `weeks` or `quarters` or `years`
* `endof` can be replaced with `startof`
* `month` can be replaced with `day` or `week` or `quarter` or `year`
  {% endhint %}

### Date macros usage examples <a href="#date-macros-usage-examples-w0wnl" id="date-macros-usage-examples-w0wnl"></a>

*In the examples below, assume that today’s date is August 26th, 2026.*&#x20;

| Parameter + macro               | Parameter + Output       |
| ------------------------------- | ------------------------ |
| `start_date: {{today}}`         | `start_date: 2026-08-26` |
| `updated_at: {{thisweekstart}}` | `updated_at: 2026-08-24` |
| `to: {{3monthsago}}`            | `to: 2026-05-26`         |
| `to: {{1yearfromnow}}`          | `to: 2027-08-26`         |

### Supported Date-time Macros <a href="#supported-date-time-macros-goput" id="supported-date-time-macros-goput"></a>

The default date and time format is YYYY-MM-DD\[T]hh:mm:ss\[Z] which corresponds to the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date.&#x20;

* `now`
* `thishourstart`
  * `this` can be replaced with `last`  or `next`
  * `start`  can be replaced with `end`
* `hourago`
* `2hoursago`
  * `2`  can be replaced with any number up to 3 digits
* `1hourfromnow`
  * `1` can be replaced with any number up to 3 digits

### Date-time macros usage examples <a href="#date-time-macros-usage-examples-hs8mz" id="date-time-macros-usage-examples-hs8mz"></a>

In the examples belo&#x77;*, assume that today’s date and time is August 26th, 2026 - 14:05.*

| Parameter + macro               | Output                                |
| ------------------------------- | ------------------------------------- |
| `created_at: {{thishourstart}}` | `created_at: 2026-08-26T14:05:00Z`    |
| `updated_since: {{5hoursago}}`  | `updated_since: 2026-08-26T09:05:00z` |
| `created_at: {{3hoursfromnow}}` | `created_at: 2026-08-26T17:05:00z`    |

### Supported custom macros formats <a href="#custom-format-k4rn0" id="custom-format-k4rn0"></a>

You can format each macro as needed using the following syntax:

`{{macro.format(output-format)}}`

* `macro` - specify the macro you need
* `output-format` - specify the format you want the macro to output
  * `dddd` - day of the week (e.g. Monday, Tuesday, Wednesday, etc.)
  * `DD` - day of the month (1-31)
  * `MM` - month (1-12)
  * `YYYY` - year (e.g.  2026)
  * `hh` - hour (0-24)
  * `mm` - minute (0-59)

<details>

<summary>Check the example</summary>

* `{{2monthsago.format(YYYY-MM-DD)}}`
  * `2` can be replaced with any number up to 3 digits
  * `months` can be replaced with `days` or `weeks` or `quarters` or `years`
  * `(YYYY-MM-SS)` can be replaced with a combination of the `output-format` examples listed above like `(MM-YYYY)`
* `{{2monthsago.endof(month).format(YYYY-MM-DD)}}`
  * `2` can be replaced with any number up to 3 digits
  * `months` can be replaced with `days` or `weeks` or `quarters` or `years`
  * `endof` can be replaced with `startof`
  * `month` can be replaced with `day` or `week` or `quarter` or `year`

</details>

### Custom macros format examples <a href="#macros-custom-format-example-hywjo" id="macros-custom-format-example-hywjo"></a>

*In the examples below, assume that today's date and time is August 26th, 2026, at 13:23.*

| Parameter + Macros:                                      | Parameter + Output:      |
| -------------------------------------------------------- | ------------------------ |
| `created_at:{{today.format(dddd)}}`                      | `created_at:Wednesday`   |
| `created_at:{{5hoursago.format(hh:mm)}}`                 | `created_at:8:23`        |
| `created_at:{{55hoursfromnow.format(YYYY-MM-DD)}}`       | `created_at:2026-08-28`  |
| `Created_at: 2monthsago.endof(month).format(YYYY-MM-DD)` | `Created_at: 2025-06-30` |

### Where can you use Macros? <a href="#where-to-use-macros-qvunj" id="where-to-use-macros-qvunj"></a>

1. **Date & date-time settings of data flow (source settings)**

<table><thead><tr><th width="181.68359375">Setting</th><th>Wizard</th></tr></thead><tbody><tr><td><strong>Report Period</strong></td><td><img src="/files/2XPeqFNduF1YuB4XWZbG" alt="" data-size="original"></td></tr><tr><td><strong>Advanced settings</strong></td><td><p><img src="/files/fmdxb9AiSc0K4LOKUKZL" alt="" data-size="original"></p><p></p></td></tr><tr><td><strong>Date filters</strong></td><td><img src="/files/ayIwdZEGfFaXwkoFQKHC" alt="" data-size="original"></td></tr></tbody></table>

{% hint style="info" %}
**HubSpot**: Only date macros are available for HubSpot date fields. Date and time macros ( {{hourago}}, etc.) are unavailable.
{% endhint %}

2. **Body/string/query settings of data flow that allow dynamic input (source settings)**

* JSON / CSV URL, URL query string, and Body fields of the JSON or CSV Client data flow.
* QuickBooks "Where" field

{% hint style="info" %}
QB requires the use of macro values in single quotes, i.e., '{{today}}'. Please find a more detailed guide for this [here](/sources/category/finance-and-accounting/quickbooks.md).
{% endhint %}

* QuickBooks reports the "Query parameters" field.
* Xero "Where" field

{% hint style="info" %}
Special formatting to be used with Xero data flow: check the details [here](/sources/category/finance-and-accounting/xero.md).
{% endhint %}

* BigQuery "SQL query" field
* JIRA "JQL" field
* Slack "Search query" field&#x20;

<details>

<summary>Examples of using macros in the URL Query Parameter and Request body for GET &#x26; POST Requests</summary>

**"URL query parameter" field for GET requests**

<div align="left"><figure><img src="/files/zwuFs7quLw7Tlt0m8Rmn" alt="" width="375"><figcaption></figcaption></figure></div>

**“Request body" field for POST requests**

The output you would see in Slack:

<div align="left"><figure><img src="/files/XjDtB0JvVu7ogZC9YOqj" alt="" width="187"><figcaption></figcaption></figure></div>

To post a message to Slack:

<div align="left"><figure><img src="/files/wAGRoNw3OE99ViwVADsf" alt="" width="375"><figcaption></figcaption></figure></div>

</details>

3. **Sheet name setting (destination settings)**

If you need the data flow to send data to a new destination sheet on each run, you may apply a macro in the name of the destination sheet.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coupler.io/functionality/macros-in-data-flows.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.