This guide helps developers using the [IAB Tech Lab Event and
Conversion API (ECAPI)](https://iabtechlab.com/standards/ecapi/) specification map their event and conversion
data to the [Data Manager API event ingestion schema](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#ingesteventsrequest).

## Overview

ECAPI is a platform-agnostic, open-source data standard that defines the
structure of marketing-related events and conversions.

The following table provides a high-level view of how key attributes and design
principles of ECAPI compare to the Data Manager API:

|   | ECAPI | Data Manager API |
|---|---|---|
| **Deduplication** | Relies on `id` (event ID) | Relies on `transaction_id` |
| **Event routing** | The `data_set_id` field in the event payload indicates the destination of the data. | The [`destinations`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#destination) field of the request defines the destinations for the events. <br /> The Data Manager API also supports routing events to [multiple destinations](https://developers.google.com/data-manager/api/devguides/events/google-ads/online/send-events#multiple-destinations) in a single request. <br /> See [Configure destinations and headers](https://developers.google.com/data-manager/api/devguides/concepts/destinations) for more information. |
| **Privacy and consent fields** | Global Privacy Platform (GPP) consent strings | The Data Manager API doesn't accept or parse Global Privacy Platform (GPP) consent strings. Set consent fields in the [`Consent`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#consent) object. <br /> You can set consent at either the request level (which applies to all events in the request) or at the event level (which lets you specify different consent settings for individual events). |

## Structural field mapping

The following mapping tables define how individual fields from the ECAPI
specification translate into fields accepted by the Data Manager API:

> [!TIP]
> **Tip:** See the [Events overview](https://developers.google.com/data-manager/api/devguides/events) to get started with sending events and to learn more about the required and optional fields for each event ingestion use case.

### Event object mapping

| ECAPI ([`event`](https://github.com/InteractiveAdvertisingBureau/ecapi/blob/main/ecapi_1.0.md#core-event-object-)) | Data Manager API ([`Event`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#event)) | Notes |
|---|---|---|
| `data_set_id` | - `destinations[].product_destination_id` (Request level) - `destination_references` (Event level) | You can define destinations at the following levels: - Request level **(Required)** : Specify the list of `destinations` in the [`IngestEventsRequest`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#ingesteventsrequest). - Event level **(Optional)** : Use the `destination_references` field on the [`Event`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#event) object. Add an entry to specify which destination from the `destinations` list should receive the event. <br /> For more information on how to define a [`Destination`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#destination) and determine the product destination ID, see [Configure destinations and headers](https://developers.google.com/data-manager/api/devguides/concepts/destinations). |
| `id` | `transaction_id` | Deduplicates conversion events. See **How Google handles multi-source data** in the **Send events** guides for [Google Ads](https://developers.google.com/data-manager/api/devguides/events/google-ads/online/send-events#update-semantics), [Google Analytics](https://developers.google.com/data-manager/api/devguides/events/analytics/online/send-events#update-semantics), and [Floodlight](https://developers.google.com/data-manager/api/devguides/events/cm360/online/send-events#update-semantics). |
| `timestamp` | `event_timestamp` | **Required.** ECAPI uses the Unix epoch format (integer) for timestamps. When mapping to the Data Manager API, convert the `event_timestamp` field to one of the following formats: - If using JSON format, set to a value in [RFC 3339](https://www.ietf.org/rfc/rfc3339) format. - If using protocol buffers, use a [`Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) and set the `seconds` and (optionally) the `nanoseconds` fields. <br /> See [Timestamp format](https://developers.google.com/data-manager/api/devguides/concepts/formatting#timestamp_format) for details. |
| `event_type` / `custom_event` | `event_name` | This can be a recommended event name (for example, `purchase`) or a custom event name. See [Standard event names](https://developers.google.com/data-manager/api/reference/ecapi#standard-event-names) for details. |
| `user_data` | `user_data` | Maps to the [`UserData`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#userdata) object, which accepts a list of [`UserIdentifier`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#useridentifier) objects. |
| `value` | `conversion_value` | Map directly as a double or float representing the monetary value of the conversion. |
| `currency_code` | `currency` | Map to a three-letter uppercase currency code (for example, `USD`). |
| `source` | `event_source` | Set to a value from the [EventSource](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#eventsource) enum. |
| `properties` | - `cart_data` - `custom_variables` - `additional_event_parameters` | Map transaction-level items to the [`cart_data.items`](https://developers.google.com/data-manager/api/reference/ecapi#item) array in the [`CartData`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#cartdata) object. The Data Manager API supports several optional [Merchant Center fields](https://developers.google.com/data-manager/api/devguides/events/google-ads/online/send-events#merchant_center_fields) for products that exist in Merchant Center accounts. <br /> If your destination is a Google Ads conversion action, you can also include additional custom parameters in the `custom_variables` field as a list of [`CustomVariable`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#customvariable) objects. <br /> If your destination is a Google Analytics data stream, you can include additional event parameters in the `additional_event_parameters` field as a list of [`AdditionalEventParameter`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#additionaleventparameter) objects. |
| `ext` | No equivalent |   |

### User data object mapping

> [!TIP]
> **Tip:** See the **Convert the data to `Event` objects** section in the destination-specific **Send events** guides (available from the [Events overview](https://developers.google.com/data-manager/api/devguides/events) for [Google Ads](https://developers.google.com/data-manager/api/devguides/events/google-ads/online/send-events#convert_to_events), [Google Analytics](https://developers.google.com/data-manager/api/devguides/events/analytics/online/send-events#convert_to_events), and [Floodlight](https://developers.google.com/data-manager/api/devguides/events/cm360/online/send-events#convert_to_events)) for more information on which identifiers are required and recommended for each destination and use case.

In the Data Manager API, the `user_data` field on the [`Event`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#event) object
accepts a [`UserData`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#userdata) object. This expects a list of
[`UserIdentifier`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#useridentifier) objects, which can contain individual
user identifiers such as email addresses, phone numbers, or address components:

| ECAPI ([`user_data`](https://github.com/InteractiveAdvertisingBureau/ecapi/blob/main/ecapi_1.0.md#user_data-object-)) | Data Manager API ([`Event`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#event)) | Notes |
|---|---|---|
| `customer_identifier` | `user_id` (Google Analytics) | For Google Analytics events, the `user_id` field represents a [User-ID](https://support.google.com/analytics/answer/9213390). The Data Manager API doesn't support generic customer ID fields for other destinations. |
| `uids` | No equivalent | The Data Manager API doesn't support a structured `uids` array containing agent types and domains. |
| `customer_segments` | `user_properties` | Map to [`UserProperties`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#userproperties) on the [`Event`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#event). |
| `email_address` | `user_data.user_identifiers[].email_address` | Set to the [formatted and hashed](https://developers.google.com/data-manager/api/devguides/concepts/formatting) email address. You can also [encrypt the hashed email address](https://developers.google.com/data-manager/api/devguides/concepts/encryption). |
| `phone_numbers` | `user_data.user_identifiers[].phone_number` | Set to the [formatted and hashed](https://developers.google.com/data-manager/api/devguides/concepts/formatting) phone number. You can also [encrypt the hashed phone number](https://developers.google.com/data-manager/api/devguides/concepts/encryption). |
| `utcoffset` | No equivalent | If you're using JSON format, you can specify the timezone offset directly in the RFC 3339 `event_timestamp` string. If you're using protocol buffers, you can use utility functions such as `Timestamps.parse(String)` to handle timezone conversion to seconds and nanos. See [Timestamp format](https://developers.google.com/data-manager/api/devguides/concepts/formatting#timestamp_format) for details. |
| `address` | `user_data.user_identifiers[].address` | Maps to an [`AddressInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#addressinfo) object. See [Address object mapping](https://developers.google.com/data-manager/api/reference/ecapi#address). |
| `gpp_string` | No equivalent | Map consent to the request-level or event-level [`Consent`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#consent) object. See the [Privacy and consent overview](https://developers.google.com/data-manager/api/reference/ecapi#overview). |
| `gpp_sid` | No equivalent | Map consent to the request-level or event-level [`Consent`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#consent) object. See the [Privacy and consent overview](https://developers.google.com/data-manager/api/reference/ecapi#overview). |
| `mmt_only` | No equivalent |   |
| `click_id` | `ad_identifiers.gclid` | Map to the Google Click ID (`gclid`). See [`AdIdentifiers`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#adidentifiers) for more details. |
| `impression_id` | `ad_identifiers.impression_id` | See [`AdIdentifiers`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#adidentifiers) for more details. |
| `event_ip_address` | `event_device_info.ip_address` | See [`DeviceInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#deviceinfo) for available fields. |
| `event_user_agent` | `event_device_info.user_agent` | See [`DeviceInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#deviceinfo) for available fields. |
| `ifa` | `ad_identifiers.mobile_device_id` | Map to the mobile identifier for advertisers (IDFA on iOS, AdID on Android). See [`AdIdentifiers`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#adidentifiers) for more details. |
| `landing_ip_address` | `ad_identifiers.landing_page_device_info.ip_address` | See [`DeviceInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#deviceinfo) for available fields. |
| `landing_user_agent` | `ad_identifiers.landing_page_device_info.user_agent` | See [`DeviceInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#deviceinfo) for available fields. |
| `age_range` | No equivalent |   |
| `gender` | No equivalent |   |
| `ext` | No equivalent |   |

### Address object mapping

| ECAPI ([`address`](https://github.com/InteractiveAdvertisingBureau/ecapi/blob/main/ecapi_1.0.md#address-object-)) | Data Manager API ([`AddressInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#addressinfo)) | Notes |
|---|---|---|
| `first_name` | `given_name` | Maps to the `given_name` field in [`AddressInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#addressinfo). Follow the [formatting and hashing guidelines](https://developers.google.com/data-manager/api/devguides/concepts/formatting). You can also [encrypt the hashed attributes of an address](https://developers.google.com/data-manager/api/devguides/concepts/encryption). |
| `last_name` | `family_name` | Maps to the `family_name` field in [`AddressInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#addressinfo). Follow the [formatting and hashing guidelines](https://developers.google.com/data-manager/api/devguides/concepts/formatting). You can also [encrypt the hashed attributes of an address](https://developers.google.com/data-manager/api/devguides/concepts/encryption). |
| `street` | No equivalent | Not supported in the Data Manager API. |
| `city` | No equivalent | Not supported in the Data Manager API. |
| `state` | No equivalent | Not supported in the Data Manager API. |
| `country_code` | `region_code` | **Don't hash** . Maps to the `region_code` field in [`AddressInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#addressinfo). Follow the [formatting guidelines](https://developers.google.com/data-manager/api/devguides/concepts/formatting). |
| `postal_code` | `postal_code` | **Don't hash** . Maps to the `postal_code` field in [`AddressInfo`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#addressinfo). Follow the [formatting guidelines](https://developers.google.com/data-manager/api/devguides/concepts/formatting). |
| `address_type` | No equivalent | Not supported in the Data Manager API. |
| `ext` | No equivalent |   |

### Item object mapping

> [!TIP]
> **Tip:** See the **Add cart data** section in the destination-specific **Send events** guides (available from the [Events overview](https://developers.google.com/data-manager/api/devguides/events) for [Google Ads](https://developers.google.com/data-manager/api/devguides/events/google-ads/online/send-events#add_cart_data), [Google Analytics](https://developers.google.com/data-manager/api/devguides/events/analytics/online/send-events#add_cart_data), and [Floodlight](https://developers.google.com/data-manager/api/devguides/events/cm360/online/send-events#add_cart_data)) for more information on which fields to include in cart data for each event ingestion use case.

| ECAPI ([`item`](https://github.com/InteractiveAdvertisingBureau/ecapi/blob/main/ecapi_1.0.md#item-object-)) | Data Manager API ([`Item`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#item)) | Notes |
|---|---|---|
| `id` | `item_id` | **Required** for Google Analytics events. Set to a standard, unique identifier for the item. |
| No equivalent | `merchant_product_id` | **Required** for Floodlight conversions and Google Ads conversions with cart data. Set to the product ID within the [Merchant Center account](https://support.google.com/merchants/answer/6324405). |
| `name` | `additional_item_parameters` | Map as `item_name` in the `additional_item_parameters` list. |
| `price` | `unit_price` |   |
| `discount` | `additional_item_parameters` or `custom_variables` | Map as `discount` in `additional_item_parameters` (for Google Analytics) or as a custom variable in `custom_variables` (for Google Ads). |
| `quantity` | `quantity` | Convert the `float` value to an integer (`int64`). |
| `brand` | `additional_item_parameters` | Map as `item_brand` in the `additional_item_parameters` list. |
| `affiliation` | `additional_item_parameters` | Map as `affiliation` in the `additional_item_parameters` list. |
| `category` | `additional_item_parameters` | Map as `item_category` in the `additional_item_parameters` list. |
| `cattax` | No equivalent |   |
| `item_coupon` | `additional_item_parameters` | Map as `coupon` in the `additional_item_parameters` list. |
| `item_list_id` | `additional_item_parameters` | Map as `item_list_id` in the `additional_item_parameters` list. |
| `item_list_name` | `additional_item_parameters` | Map as `item_list_name` in the `additional_item_parameters` list. |
| `item_item_variant` | `additional_item_parameters` | Map as `item_variant` in the `additional_item_parameters` list. |
| `item_location_id` | `additional_item_parameters` | Map as `location_id` in `additional_item_parameters`. |
| `ext` | No equivalent |   |

## Standard event names

[ECAPI standard events](https://github.com/InteractiveAdvertisingBureau/ecapi/blob/main/ecapi_1.0.md#standard-events-) heavily align with Google Analytics
naming conventions.

- If you're sending events to a Google Analytics data stream, the `event_name` field is
  **required**.

- See the
  [Google Analytics recommended events reference](https://developers.google.com/data-manager/api/reference/analytics/recommended-events) for
  associated fields, parameters, and sample Data Manager API ingestion requests
  for each event.

- You can also send [Custom events](https://support.google.com/analytics/answer/12229021) provided they follow
  the [Event naming rules](https://support.google.com/analytics/answer/13316687).

Most [ECAPI standard events](https://github.com/InteractiveAdvertisingBureau/ecapi/blob/main/ecapi_1.0.md#standard-events-) (such as `purchase`,
`add_to_cart`, `begin_checkout`, `search`, and `refund`) have the same event
name as Google Analytics recommended events. However, there are a few exceptions where
Google Analytics uses present tense instead of past tense:

- `viewed_item` maps to `view_item`

- `viewed_item_list` maps to `view_item_list`

- `viewed_cart` maps to `view_cart`

## Example requests

The following tabs show a comparison between an ECAPI conversion event payload
and its representation as a valid Data Manager API
[`IngestEventsRequest`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#ingesteventsrequest):

### ECAPI

Here's a sample JSON payload conforming to the ECAPI specification:

    {
      "data_set_id": "123456789",
      "id": "ABC798654321",
      "timestamp": 1781035621,
      "event_type": "purchase",
      "value": 30.03,
      "currency_code": "USD",
      "source": "website",
      "user_data": {
        "customer_identifier": "123456789123456789",
        "customer_segments": ["gold_member"],
        "email_addresses": [
          "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
        ],
        "address": {
          "first_name": "96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a",
          "last_name": "db98d2607efffa28aff66975868bf54c075eca7157e35064dce08e20b85b1081",
          "country_code": "US",
          "postal_code": "94045"
        },
        "event_ip_address": "192.0.2.1",
        "event_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
      },
      "properties": {
        "items": [
          {
            "id": "SKU_12345",
            "quantity": 3,
            "item_price": 10.01
          }
        ]
      }
    }

### Data Manager API

Here's a sample [`IngestEventsRequest`](https://developers.google.com/data-manager/api/reference/rpc/google.ads.datamanager.v1#ingesteventsrequest) for
the formatted, hashed, and encoded event data. The `GOOGLE_ADS` account
type in the destination indicates that the request targets a Google Ads
destination:

    {
      "destinations": [
        {
          "operating_account": {
            "account_type": "GOOGLE_ADS",
            "account_id": "1234567890"
          },
          "login_account": {
            "account_type": "GOOGLE_ADS",
            "account_id": "1234567890"
          },
          "product_destination_id": "123456789"
        }
      ],
      "encoding": "HEX",
      "events": [
        {
          "event_name": "purchase",
          "transaction_id": "ABC798654321",
          "event_timestamp": "2026-06-10T20:07:01Z",
          "event_source": "WEB",
          "user_properties": {
            "additional_user_properties":[
              {
                "property_name": "customer_segment",
                "value": "gold_member"
              }
            ]
          },
          "user_data": {
            "user_identifiers": [
              {
                "email_address": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
              },
              {
                "address": {
                  "given_name": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
                  "family_name": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
                  "region_code": "US",
                  "postal_code": "94045"
                }
              }
            ]
          },
          "event_device_info": {
            "ip_address": "192.0.2.1",
            "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
          },
          "conversion_value": 30.03,
          "currency": "USD",
          "cart_data": {
            "items": [
              {
                "item_id": "SKU_12345",
                "quantity": 3,
                "unit_price": 10.01
              }
            ]
          }
        }
      ]
    }