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

# Events & Attribution

> Look up individual clicks, conversions, transaction attribution chains, and store orders.

Click, conversion, transaction, and order records are served through the generic entity tools — [`get_entity`](generic#get_entity) for a single record by ID, [`list_entities`](generic#list_entities) for filtered listings. This page documents their filters and response shapes, and how to choose between them and the reporting tools.

## Choosing the right tool

| You need                                                                   | Use                                                                          |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| One click or conversion by ID                                              | `get_entity(type="click", id=…)` / `get_entity(type="conversion", id=…)`     |
| The full story of one transaction — click, conversions, pixel fires, holds | `get_entity(type="transaction", id=…)`                                       |
| Which store an order came from — map a store order id to its store         | `get_entity(type="order", id=…)`                                             |
| Raw click/conversion records over a time window                            | [`search_activity`](reporting#search_activity) — purpose-built stream search |
| Filtered, cursor-paginated event listings                                  | [`list_entities`](generic#list_entities) with the filters below              |
| Aggregated stats (totals, trends, breakdowns)                              | [`run_performance_report`](reporting#run_performance_report)                 |

Clicks and transactions are identified by the **32-character transaction ID**; conversions by the **conversion ID**.

<Note>
  In event responses, most empty, zero, or false fields are omitted — any given record may carry only a subset of the keys listed below (e.g. `campaign_id`, `error_message`, `coupon_code`, `is_view_through`, and `is_test_mode` appear only when set). A few string fields (e.g. `browser`, `os_version`, `referer`, `coupon_code`) may instead come back as an empty string `""` rather than being dropped — treat "key absent" and "empty string" the same way.
</Note>

## Click

```text theme={null}
get_entity(type="click", id="<32-char transaction ID>")
```

Use this as the first step when a partner reports a missing click, a tracking failure, or an attribution dispute.

**Response fields:** `transaction_id`, `timestamp`, `offer_id`, `offer_name`, `affiliate_id`, `affiliate_name`, `advertiser_id`, `advertiser_name`, `campaign_id`, `error_code`, `error_message`, `is_unique`, `is_view_through`, `is_test_mode`, `payout`, `revenue`, `currency`, `country`, `region`, `city`, `browser`, `platform`, `device_type`, `os_version`, `user_ip`, `sub1`–`sub10`, `source_id`, `referer`, `coupon_code`, `has_conversion`, `previous_transaction_id`.

### Listing clicks

`list_entities(type="click", filters=…)` accepts:

| Filter           | Type   | Description                                                                         |
| ---------------- | ------ | ----------------------------------------------------------------------------------- |
| `from`           | string | Start of the search range (e.g. `2024-01-01`) — **required for listing**            |
| `to`             | string | End of the search range — **required for listing**, maximum **14-day** range        |
| `transaction_id` | string | The unique transaction ID                                                           |
| `offer_id`       | number | Filter by offer ID                                                                  |
| `affiliate_id`   | number | Filter by affiliate ID                                                              |
| `advertiser_id`  | number | Filter by advertiser ID                                                             |
| `error_code`     | number | Filter by click error code (use the `click_error_code` entity type for definitions) |
| `country`        | string | Filter by country code                                                              |
| `source_id`      | string | Filter by traffic source ID                                                         |
| `sub1`–`sub10`   | string | Filter by sub parameter value                                                       |

## Conversion

```text theme={null}
get_entity(type="conversion", id="<conversion ID>")
```

Use this to verify attribution and payout accuracy for a single conversion.

**Response fields:** `conversion_id`, `transaction_id`, `timestamp`, `click_timestamp`, `status`, `error_code`, `error_message`, `offer_id`, `offer_name`, `affiliate_id`, `affiliate_name`, `advertiser_id`, `advertiser_name`, `campaign_id`, `payout`, `revenue`, `sale_amount`, `payout_type`, `revenue_type`, `currency`, `event_id`, `event_name`, `order_id`, `coupon_code`, `email`, `notes`, `is_scrub`, `is_view_through`, `country`, `region`, `city`, `platform`, `device_type`, `browser`, `os_version`, `sub1`–`sub10`, `adv1`–`adv10`, `source_id`, `referer`.

<Note>
  `email` is the customer email recorded on the conversion. For conversions from GDPR
  countries it is returned **obfuscated** — the local part is masked, leaving the first
  character and the domain (`a*******@example.com`) — and returned unchanged otherwise.
  This matches how the same field is surfaced in the network conversion report. It is
  omitted entirely when the conversion carries no email.
</Note>

### Listing conversions

`list_entities(type="conversion", filters=…)` accepts:

| Filter           | Type   | Description                                                                                                                                            |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `from`           | string | Start of the search range (e.g. `2024-01-01`) — **required for listing** (except when `transaction_id` is given)                                       |
| `to`             | string | End of the search range — **required for listing** (except when `transaction_id` is given)                                                             |
| `transaction_id` | string | 32-char transaction ID — returns every conversion sharing it as a **flat, paginated list**, no date range needed. Cannot be combined with `from`/`to`. |
| `conversion_id`  | string | The unique conversion ID                                                                                                                               |
| `status`         | string | `approved`, `pending`, `rejected`, or `invalid`                                                                                                        |
| `offer_id`       | number | Filter by offer ID                                                                                                                                     |
| `affiliate_id`   | number | Filter by affiliate ID                                                                                                                                 |
| `advertiser_id`  | number | Filter by advertiser ID                                                                                                                                |
| `country`        | string | Filter by country code                                                                                                                                 |
| `source_id`      | string | Filter by traffic source ID                                                                                                                            |
| `sub1`–`sub10`   | string | Filter by sub parameter value                                                                                                                          |
| `adv1`–`adv10`   | string | Filter by advertiser parameter value                                                                                                                   |

<Note>
  **Conversions for a transaction:** `list_entities(type="conversion", filters={"transaction_id":"<32-char id>"})` is the flat alternative to `get_entity(type="transaction")`. It returns the same conversions, but **cursor-paginated instead of capped at 10** and without the click / pixel / on-hold wrapper. Because it's an indexed lookup, no `from`/`to` window is required.
</Note>

## Transaction

```text theme={null}
get_entity(type="transaction", id="<32-char transaction ID>")
```

Returns the full attribution chain for a transaction in one call — use it for end-to-end attribution debugging. Transactions are fetched by ID only; there are no listing filters.

| Field                 | Description                                                                                                                                                                                      |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `transaction_id`      | The transaction ID                                                                                                                                                                               |
| `click`               | The click object (same fields as `type="click"`)                                                                                                                                                 |
| `conversions`         | Array of conversion objects (same fields as `type="conversion"`, each with an added `attribution_method`)                                                                                        |
| `pixels`              | Affiliate pixel-fire logs: `network_pixel_id`, `pixel_type`, `pixel_level`, `pixel_status`, `delivery_method`, `is_success`, `conversion_id`, `transaction_id`, `timestamp`, `debug_information` |
| `on_hold_conversions` | Held/pending conversions: `on_hold_conversion_id`, `status`, `holding_period_end`, `timestamp`, `payout`, `revenue`, `sale_amount`, `notes`, `conversion_id`                                     |

Each collection is capped (10 items) to stay within the context window. For each, the response includes `<name>_total` and `<name>_returned`; a `<name>_truncated: true` flag is added **only when** the collection exceeded the cap (it is omitted otherwise). Compare `<name>_total` with `<name>_returned` to detect when there's more than what's shown. When conversions are truncated, `conversions_note` gives the exact `list_entities(type="conversion", filters={"transaction_id":…})` call to page through all of them.

## Order

```text theme={null}
get_entity(type="order", id="<store order id>")
```

An e-commerce order ingested from a store integration. Use this to map a store order id back to the **store** it came from — for Shopify, the `.myshopify.com` URL — and to the transaction it generated. The `id` is the store's order id (the long Shopify order id, **not** the 32-char transaction ID).

**Response fields:** `order_id`, `order_number`, `transaction_id`, `source`, `integration_id`, `shopify_store_url`, `offer_id`, `affiliate_id`, `customer_email`, `total`, `timestamp`, `items` (each: `product_id`, `sku`, `name`, `quantity`, `price`). `shopify_store_url` is populated for Shopify orders only; `integration_id` is the store's integration ID on the network.

### Listing orders

`list_entities(type="order", filters=…)` accepts:

| Filter           | Type   | Description                                                                                                                   |
| ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `order_id`       | string | The store's order id — returns that one order (prefer `get_entity(type="order", id=…)`)                                       |
| `integration_id` | number | List **all Shopify orders for one store** — its `network_integration_shopify_v2_id`. Requires `from`/`to`                     |
| `from`           | string | Start of the window (`YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`, **UTC**) — required with `integration_id`                         |
| `to`             | string | End of the window (same format, **UTC**) — required with `integration_id`; the `from`→`to` window may not exceed **3 months** |

<Note>
  The by-integration listing is backed by the order line-item table, not the order store, so it returns a lighter record (no `total`, `customer_email`, offer/affiliate ids, or line `items` — fetch a single order by id for those) and **excludes orders that have no line items**. It's scanned newest-first in bounded chunks; a `has_more: true` with a `note` means more orders match or the scan budget was reached — narrow the window to see the rest.
</Note>

<Note>
  The former `get_click` and `get_conversion` tools remain callable for backward compatibility but are deprecated and no longer listed — see [Deprecated tools](../tools#deprecated-tools).
</Note>