> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metricanic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# URL macros

> Pass visit and event values between traffic sources, pages, offers, and postbacks.

A URL macro is a placeholder replaced with a value when a tracking action occurs. Use macros to carry attribution into an offer, pass ad metadata to a page, or build an outgoing conversion notification.

There are several handoffs in a tracking setup. The system that expands a placeholder matters as much as its name.

## Know who replaces each value

| Where you configure it        | Who expands it                                          | Example purpose                                     |
| ----------------------------- | ------------------------------------------------------- | --------------------------------------------------- |
| Traffic source's Macro column | The traffic source, before the visitor arrives          | Insert the source's creative or ad click ID         |
| Landing or offer URL          | Metricanic, when generating the tracked destination URL | Pass `{click_id}` or `{token1}` to the page         |
| Affiliate network callback    | The affiliate network, when sending an event            | Return the Metricanic click ID it stored earlier    |
| Outgoing postback URL         | Metricanic, after applying event settings               | Return `{external_id}` and `{payout}` to the source |

Do not copy a macro from one system into another unless that receiver supports it. Two providers can use similar names for different identifiers.

## Start with attribution and source tokens

These Metricanic macros are the most common in landing and offer URLs:

| Macro                          | Value                                                           |
| ------------------------------ | --------------------------------------------------------------- |
| `{click_id}`                   | Metricanic's signed click ID used for attribution               |
| `{external_id}`                | The original traffic source click ID captured at arrival        |
| `{campaign_id}`                | Metricanic campaign ID                                          |
| `{token1}` through `{token15}` | Values captured in the corresponding traffic source token slots |
| `{visit_cost}`                 | Recorded visit cost                                             |
| `{visit_ts}`                   | Visit timestamp in milliseconds since the Unix epoch            |
| `{country}`                    | Country name                                                    |
| `{country_code}`               | Uppercase country code                                          |

For example, map the source's `creative` parameter into Token 1 and capture its ad click ID in the **Click ID** row. Then configure the offer URL as:

```text theme={null}
https://offer.example.com/signup?subid={click_id}&creative={token1}&source_click={external_id}
```

Metricanic generates a destination URL with three different values. The conversion sender must return the value received in `subid`. The other two values can support its own analysis or source attribution.

Use the numbered token macro even when the token has a readable alias such as Creative. The alias labels the slot. It does not create an arbitrary `{Creative}` replacement.

## Use request context only where available

The macro picker next to a URL lists the set appropriate for that field. Landing and offer URL pickers include geography, language, IP, user agent, device, operating system, browser, and network fields such as:

```text theme={null}
{region} {city} {language} {user_ip} {user_agent}
{device_type} {os_family} {browser_name} {asn}
```

The landing URL picker also includes fields such as `{ref_domain}` and `{ref_url}`. Do not assume that every field available at arrival is also available when a later offer click is processed. A supported field can be missing for a particular request.

`{lp_key}` supplies a landing protection token. It requires server-side verification and is separate from click attribution. Follow [landing protection](/tracking/landing-protection) for its setup and limitations.

In Direct Script Mode, the browser has already loaded the arrival page. Saving Metricanic macros in that page's configured URL does not cause an earlier ad-platform request to be expanded by Metricanic. Use the generated direct integration and [landing script](/tracking/landings) to work with the registered visit.

## Add event values to outgoing postbacks

Event macros become useful after Metricanic receives and processes an event:

| Macro             | Value                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------- |
| `{payout}`        | Valid incoming payout when supplied, otherwise an available configured payout               |
| `{event_cost}`    | Configured event cost for ordinary incoming events, including a fixed cost or revenue share |
| `{profit}`        | Outgoing `{payout}` minus outgoing `{event_cost}`, when both are available                  |
| `{event_value}`   | Incoming event value                                                                        |
| `{event_idx}`     | Event ID                                                                                    |
| `{event_ts}`      | Event timestamp in milliseconds                                                             |
| `{tx_uid}`        | Transaction identifier in the processed event context                                       |
| `{is_conversion}` | Whether the event counts as a conversion, as `1` or `0`                                     |

`{payout}` does not always equal the revenue recorded in reports. For example, incoming `payout=100` with **Revenue** set to **Fixed amount = 80** records USD 80 revenue but sends `100` through `{payout}`.

`{event_cost}` uses the cost calculated by the event action for incoming `/event` requests. `{profit}` uses the outgoing macro amounts, so it can differ from recorded event revenue minus cost. It does not subtract visit cost or represent the campaign's total profit.

For a source that accepts these example parameter names, an outgoing URL could be:

```text theme={null}
https://source.example.com/conversion?id={external_id}&amount={payout}&event={event_idx}
```

Use the source's actual receiving URL and parameter names. See [outgoing postbacks](/conversions/postbacks) for the complete setup.

### Send 50% with the event cost macro

To send half of each incoming payout, set **Revenue** to **From incoming event**, set **Event cost** to **Revenue share (%)** with `50`, and use `{event_cost}` as the outgoing amount:

```text theme={null}
https://receiver.example.com/conversion?id={external_id}&payout={event_cost}
```

The **Revenue** selector is available in **Advanced**. **Simple** already uses incoming payout.

An incoming `payout=100` produces an outgoing `payout=50` in this example. The receiver's parameter can be called `payout` even though the value comes from `{event_cost}`.

Selecting the revenue share normally also adds that USD 50 to report costs. Follow the [complete percentage postback setup](/conversions/postbacks#send-50-percent-of-revenue-in-an-outgoing-postback) before using it. Macros such as `{payout:50}` or `{payout*0.5}` are not supported and do not calculate a reduced amount.

## Verify the expanded request

Metricanic URL-encodes replacement values. A space in a value becomes `%20`, so use macros as individual parameter values and avoid encoding them a second time.

Unknown macros and macros without a value remain unchanged. A saved template is therefore not proof that every placeholder will resolve.

Test a real campaign arrival, offer click, or event for the stage you are configuring. Inspect the resulting destination request or outgoing postback. If a placeholder remains, check its spelling, the relevant macro picker, and whether the source data was captured. If a conversion fails, first confirm that the returned ID came from `{click_id}` rather than `{external_id}`.