# 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="https://2487187314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCgnmco7kCnvytNIN8YdT%2Fuploads%2FxhBFbv5PQ7DmGFC8ml3E%2Fimage.png?alt=media&#x26;token=731d0f2c-59b6-4903-a852-19e3617f3dd0" 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="https://2487187314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCgnmco7kCnvytNIN8YdT%2Fuploads%2Fxzu9cKuD7wNMKWbtng2T%2FScreenshot%202026-03-15%20at%2018.05.55.png?alt=media&#x26;token=0b20c0c3-04a9-434a-93f7-7f58366f5bf1" alt="" data-size="original"></td></tr><tr><td><strong>Advanced settings</strong></td><td><p><img src="https://2487187314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCgnmco7kCnvytNIN8YdT%2Fuploads%2Fuhru2Q9LlqUBazc7YXdD%2FScreenshot%202026-03-15%20at%2018.16.15.png?alt=media&#x26;token=ee4680a7-1327-44aa-85b2-cd79ff2de83d" alt="" data-size="original"></p><p></p></td></tr><tr><td><strong>Date filters</strong></td><td><img src="https://2487187314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCgnmco7kCnvytNIN8YdT%2Fuploads%2F158C18Kr9e3aWfHXa8L6%2Fimage.png?alt=media&#x26;token=3b498b0e-0180-4cc5-8ddd-2d028ff8662c" 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](https://app.gitbook.com/s/OFxU2LUkJMCfvbE2re5C/category/finance-and-accounting/quickbooks).
{% 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](https://app.gitbook.com/s/OFxU2LUkJMCfvbE2re5C/category/finance-and-accounting/xero).
{% 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="https://2487187314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCgnmco7kCnvytNIN8YdT%2Fuploads%2F64pmQmuzpAkpnLIgjedO%2Fimage.png?alt=media&#x26;token=6769fde3-0e4e-4d21-b839-cb31da45a34b" 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="https://2487187314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCgnmco7kCnvytNIN8YdT%2Fuploads%2FtVyuqN2vDsY0Qpp2bi5q%2Fimage.png?alt=media&#x26;token=a8b40120-554a-4dad-adac-c0c52f3a65db" alt="" width="187"><figcaption></figcaption></figure></div>

To post a message to Slack:

<div align="left"><figure><img src="https://2487187314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCgnmco7kCnvytNIN8YdT%2Fuploads%2FNIXilgrTmOXEGUdeJ4U8%2Fimage.png?alt=media&#x26;token=ead6ff4a-4217-4351-93ea-58f0b22447f9" 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.