Google Analytics [sends some event types
automatically](https://support.google.com/analytics/answer/9234069). This page
describes optional, additional events you can configure to measure more
behaviors and generate more useful reports for your business. These additional
events take more effort to configure before you can use them, so Google
Analytics can't send them automatically. For step-by-step instructions on how
to configure recommended and custom events for your website or app, see [Set up
events](https://developers.google.com/analytics/devguides/collection/ga4/events).

To view details of each event you can use, select your tag management platform:

<button value="gtag" default="">gtag.js</button> <button value="gtm">Tag Manager</button> <button value="firebase">Firebase</button>

## For all properties

### `earn_virtual_currency`

This event measures when a user is awarded virtual currency in a game.
Log this along with [spend_virtual_currency](https://developers.google.com/analytics/devguides/collection/ga4/reference/events#spend_virtual_currency) to better understand your
virtual economy.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `virtual_currency_name` | `string` | No | Gems | The name of the virtual currency. |
| `value` | `number` | No | 5 | The value of the virtual currency. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "earn_virtual_currency", {
      virtual_currency_name: "Gems",
      value: 5
    });

### `join_group`

Log this event when a user joins a group such as a guild, team, or family. Use
this event to analyze how popular certain groups or social features are.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `group_id` | `string` | No | G_12345 | The ID of the group. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "join_group", {
      group_id: "G_12345"
    });

### `login`

Send this event to signify that a user has logged in to your website or app.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `method` | `string` | No | Google | The method used to login. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "login", {
      method: "Google"
    });

### `search`

Log this event to indicate when the user has performed a search. You can use
this event to identify what users are searching for on your website or app. For
example, you could send this event when a user views a search results page after
performing a search.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `search_term` | `string` | **Yes** | t-shirts | The term that was searched for. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "search", {
      search_term: "t-shirts"
    });

### `select_content`

This event signifies that a user has selected some content of a certain type.
This event can help you identify popular content and categories of content on
your website or app.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `content_type` | `string` | No | product | The type of selected content. |
| `content_id` | `string` | No | C_12345 | An identifier for the content that was selected. The value must include at least one non-numeric character. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "select_content", {
      content_type: "product",
      content_id: "C_12345"
    });

### `share`

Use this event when a user has shared content.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `method` | `string` | No | Twitter | The method in which the content is shared. |
| `content_type` | `string` | No | image | The type of shared content. |
| `item_id` | `string` | No | C_12345 | The ID of the shared content. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "share", {
      method: "Twitter",
      content_type: "image",
      item_id: "C_12345",
    });

### `sign_up`

This event indicates that a user has signed up for an account. Use this event to
understand the different behaviors of logged in and logged out users.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `method` | `string` | No | Google | The method used for sign up. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "sign_up", {
      method: "Google"
    });

### `spend_virtual_currency`

This event measures the sale of virtual goods in your app and helps you identify
which virtual goods are the most popular.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `value` | `number` | **Yes** | 5 | The value of the virtual currency. |
| `virtual_currency_name` | `string` | **Yes** | Gems | The name of the virtual currency. |
| `item_name` | `string` | No | Starter Boost | The name of the item the virtual currency is being used for. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "spend_virtual_currency", {
      value: 5,
      virtual_currency_name: "Gems",
      item_name: "Starter Boost"
    });

### `tutorial_begin`

This event signifies the start of the on-boarding process. Use this in a funnel
with [tutorial_complete](https://developers.google.com/analytics/devguides/collection/ga4/reference/events#tutorial_complete) to understand how many users complete the tutorial.

#### Parameters

There are no parameters for this event.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "tutorial_begin");

### `tutorial_complete`

This event signifies the user's completion of your on-boarding process. Use this
in a funnel with [tutorial_begin](https://developers.google.com/analytics/devguides/collection/ga4/reference/events#tutorial_begin) to understand how many users complete the
tutorial.

#### Parameters

No parameters are suggested for this event.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "tutorial_complete");

## Online sales

### `add_payment_info`

This event signifies a user has submitted their payment information in an
ecommerce checkout process.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the items associated with the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* Value metrics on the `view_item` event to not contribute to revenue <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* Set `value` to the sum of `(price * quantity)` for all items in `items`. Don't include `shipping` or `tax`. \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the event. <br /> Event-level and item-level `coupon` parameters are independent. |
| `payment_type` | `string` | No | Credit Card | The chosen method of payment. |
| `items` | `Array<Item>` | **Yes** |   | The items for the event. |

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "add_payment_info", {
      currency: "USD",
      value: 30.03,
      coupon: "SUMMER_FUN",
      payment_type: "Credit Card",
      items: [
        {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          google_business_vertical: "retail",
          quantity: 3
        }
      ]
    });

### `add_shipping_info`

This event signifies a user has submitted their shipping information in an
ecommerce checkout process.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the items associated with the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* Value metrics on the `view_item` event to not contribute to revenue <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* Set `value` to the sum of `(price * quantity)` for all items in `items`. Don't include `shipping` or `tax`. \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the event. <br /> Event-level and item-level `coupon` parameters are independent. |
| `shipping_tier` | `string` | No | Ground | The shipping tier (e.g. `Ground`, `Air`, `Next-day`) selected for delivery of the purchased item. |
| `items` | `Array<Item>` | **Yes** |   | The items for the event. |

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "add_shipping_info", {
      currency: "USD",
      value: 30.03,
      coupon: "SUMMER_FUN",
      shipping_tier: "Ground",
      items: [
        {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          google_business_vertical: "retail",
          quantity: 3
        }
      ]
    });

### `add_to_cart`

This event signifies that an item was added to a cart for purchase.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the items associated with the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* Value metrics on the `view_item` event to not contribute to revenue <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* Set `value` to the sum of `(price * quantity)` for all items in `items`. Don't include `shipping` or `tax`. \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `items` | `Array<Item>` | **Yes** |   | The items for the event. |

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "add_to_cart", {
      currency: "USD",
      value: 30.03,
      items: [
        {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          google_business_vertical: "retail",
          quantity: 3
        }
      ]
    });

### `add_to_wishlist`

The event signifies that an item was added to a wishlist. Use this event to
identify popular gift items in your app.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the items associated with the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* Value metrics on the `view_item` event to not contribute to revenue <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* Set `value` to the sum of `(price * quantity)` for all items in `items`. Don't include `shipping` or `tax`. \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `items` | `Array<Item>` | **Yes** |   | The items for the event. |

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "add_to_wishlist", {
      currency: "USD",
      value: 30.03,
      items: [
        {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          google_business_vertical: "retail",
          quantity: 3
        }
      ],
    });

### `begin_checkout`

This event signifies that a user has begun a checkout.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the items associated with the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* Value metrics on the `view_item` event to not contribute to revenue <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* Set `value` to the sum of `(price * quantity)` for all items in `items`. Don't include `shipping` or `tax`. \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the event. <br /> Event-level and item-level `coupon` parameters are independent. |
| `items` | `Array<Item>` | **Yes** |   | The items for the event. |

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "begin_checkout", {
      currency: "USD",
      value: 30.03,
      coupon: "SUMMER_FUN",
      items: [
        {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          google_business_vertical: "retail",
          quantity: 3
        }
      ]
    });

### `purchase`

This event signifies when one or more items is purchased by a user.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the items associated with the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* Value metrics on the `view_item` event to not contribute to revenue <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* Set `value` to the sum of `(price * quantity)` for all items in `items`. Don't include `shipping` or `tax`. \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `customer_type` | `string` (`new` / `returning`) | No | new | Is the conversion from a \`new\` or \`returning\` customer? - `new`: New customer who hasn't purchased within a given time period (540-day window recommended and set at default, but not required). - `returning`: A returning customer who has purchased during the given time period. <br /> Don't specify a value if there's uncertainty (for example, if the user checked out as a guest). |
| `transaction_id` | `string` | **Yes** | T_12345 | The unique identifier of a transaction. <br /> The `transaction_id` parameter helps you avoid getting duplicate events for a purchase. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the event. <br /> Event-level and item-level `coupon` parameters are independent. |
| `shipping` | `number` | No | 3.33 | Shipping cost associated with a transaction. |
| `tax` | `number` | No | 1.11 | Tax cost associated with a transaction. |
| `items` | `Array<Item>` | **Yes** |   | The items for the event. |

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "purchase", {
        transaction_id: "T_12345",
        // Sum of (price * quantity) for all items.
        value: 72.05,
        tax: 3.60,
        shipping: 5.99,
        currency: "USD",
        coupon: "SUMMER_SALE",
        customer_type: "new",
        items: [
         {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          google_business_vertical: "retail",
          quantity: 3
        },
        {
          item_id: "SKU_12346",
          item_name: "Google Grey Women's Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          discount: 3.33,
          index: 1,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "gray",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 21.01,
          promotion_id: "P_12345",
          promotion_name: "Summer Sale",
          google_business_vertical: "retail",
          quantity: 2
        }]
    });

### `refund`

This event signifies when one or more items is refunded to a user.

> [!NOTE]
> **Note:** We recommend that you include item information in your `refund` event to see item-level refund metrics in Analytics.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the items associated with the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* Value metrics on the `view_item` event to not contribute to revenue <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `transaction_id` | `string` | **Yes** | T_12345 | The unique identifier of a transaction. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* Set `value` to the sum of `(price * quantity)` for all items in `items`. Don't include `shipping` or `tax`. \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the event. <br /> Event-level and item-level `coupon` parameters are independent. |
| `shipping` | `number` | No | 3.33 | Shipping cost associated with a transaction. |
| `tax` | `number` | No | 1.11 | Tax cost associated with a transaction. |
| `items` | ` https://developers.google.com/analytics/devguides/collection/ga4/reference/events#refund_item ` | No\* |   | The items for the event. |

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "refund", {
      currency: "USD",
      transaction_id: "T_12345", // Transaction ID. Required for purchases and refunds.
      value: 30.03,
      coupon: "SUMMER_FUN",
      shipping: 3.33,
      tax: 1.11,
      items: [
        {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          google_business_vertical: "retail",
          quantity: 3
        }
      ]
    });

### `remove_from_cart`

This event signifies that an item was removed from a cart.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the items associated with the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* Value metrics on the `view_item` event to not contribute to revenue <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* Set `value` to the sum of `(price * quantity)` for all items in `items`. Don't include `shipping` or `tax`. \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `items` | `Array<Item>` | **Yes** |   | The items for the event. |

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "remove_from_cart", {
      currency: "USD",
      value: 30.03,
      items: [
        {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          google_business_vertical: "retail",
          quantity: 3
        }
      ]
    });

### `select_item`

This event signifies an item was selected from a list.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> Ignored if set at the item-level. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> Ignored if set at the item-level. |
| `items` | `https://developers.google.com/analytics/devguides/collection/ga4/reference/events#select_item_item` | **Yes** |   | The items for the event. |

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "select_item", {
      currency: "USD",
      item_list_id: "related_products",
      item_list_name: "Related products",
      items: [
        {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          google_business_vertical: "retail",
          quantity: 3
        }
      ]
    });

### `select_promotion`

This event signifies a promotion was selected from a list.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `creative_name` | `string` | No | summer_banner2 | The name of the promotional creative. |
| `creative_slot` | `string` | No | featured_app_1 | The name of the promotional creative slot associated with the event. |
| `promotion_id` | `string` | No | P_12345 | The ID of the promotion associated with the event. |
| `promotion_name` | `string` | No | Summer Sale | The name of the promotion associated with the event. |
| `items` | ` https://developers.google.com/analytics/devguides/collection/ga4/reference/events#select_promotion_item` | **No\*** |   | The items for the event. <br /> \* If the `items` array is not included, then some reports, such as the [Promotions report](https://support.google.com/analytics/answer/13458990), and metrics won't include this promotion event. |

> [!NOTE]
> To populate item-scoped promotion dimensions, such as "Item promotion ID" or "Item promotion name", in Google Analytics reports, Google Analytics first looks for the corresponding promotion parameters (`promotion_id`, `promotion_name`, `creative_name`, and `creative_slot`) within each specific object in the `items` array of your ecommerce events. If a parameter is not found within the item object, Google Analytics will then use the value from the \*event-level\* parameter if one is provided. An item-scoped promotion dimension for a particular item will only report as "(not set)" if the relevant parameter is missing from \*both\* the item object and the event-level parameters. Item-level parameters always take precedence over event-level parameters.

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `creative_name` | `string` | No | summer_banner2 | The name of the promotional creative. <br /> Defaults to event-level `creative_name` if not set. |
| `creative_slot` | `string` | No | featured_app_1 | The name of the promotional creative slot associated with the item. <br /> Defaults to event-level `creative_slot` if not set. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `promotion_id` | `string` | No | P_12345 | The ID of the promotion associated with the item. <br /> Defaults to event-level `promotion_id` if not set. |
| `promotion_name` | `string` | No | Summer Sale | The name of the promotion associated with the item. <br /> Defaults to event-level `promotion_name` if not set. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "select_promotion", {
      currency: "USD",
      creative_name: "Summer Banner",
      creative_slot: "featured_app_1",
      promotion_id: "P_12345",
      promotion_name: "Summer Sale",
      items: [
        {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          creative_name: "summer_banner2",
          creative_slot: "featured_app_1",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          promotion_id: "P_12345",
          promotion_name: "Summer Sale",
          google_business_vertical: "retail",
          quantity: 3
        }
      ],
    });

### `view_cart`

This event signifies that a user viewed their cart.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the items associated with the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* Value metrics on the `view_item` event to not contribute to revenue <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* Set `value` to the sum of `(price * quantity)` for all items in `items`. Don't include `shipping` or `tax`. \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `items` | `Array<Item>` | **Yes** |   | The items for the event. |

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "view_cart", {
      currency: "USD",
      value: 30.03,
      items: [
        {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          google_business_vertical: "retail",
          quantity: 3
        }
      ]
    });

### `view_item`

This event signifies that some content was shown to the user. Use this event to
discover the most popular items viewed.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the items associated with the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* Value metrics on the `view_item` event to not contribute to revenue <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* Set `value` to the sum of `(price * quantity)` for all items in `items`. Don't include `shipping` or `tax`. \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `items` | `Array<Item>` | **Yes** |   | The items for the event. |

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "view_item", {
      currency: "USD",
      value: 30.03,
      items: [
        {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          google_business_vertical: "retail",
          quantity: 3
        }
      ]
    });

### `view_item_list`

Log this event when the user has been presented with a list of items of a
certain category.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the items associated with the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> Value metrics on the `view_item` event to not contribute to revenue <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> Ignored if set at the item-level. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> Ignored if set at the item-level. |
| `items` | `Array<Item>` | **Yes** |   | The items for the event. |

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "view_item_list", {
      currency: "USD",
      item_list_id: "related_products",
      item_list_name: "Related products",
      items: [
        {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          google_business_vertical: "retail",
          quantity: 3
        }
      ]
    });

### `view_promotion`

This event signifies a promotion was viewed from a list.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `creative_name` | `string` | No | summer_banner2 | The name of the promotional creative. |
| `creative_slot` | `string` | No | featured_app_1 | The name of the promotional creative slot associated with the event. |
| `promotion_id` | `string` | No | P_12345 | The ID of the promotion associated with the event. |
| `promotion_name` | `string` | No | Summer Sale | The name of the promotion associated with the event. |
| `items` | `https://developers.google.com/analytics/devguides/collection/ga4/reference/events#view_promotion_item` | **Yes** |   | The items for the event. |

> [!NOTE]
> To populate item-scoped promotion dimensions, such as "Item promotion ID" or "Item promotion name", in Google Analytics reports, Google Analytics first looks for the corresponding promotion parameters (`promotion_id`, `promotion_name`, `creative_name`, and `creative_slot`) within each specific object in the `items` array of your ecommerce events. If a parameter is not found within the item object, Google Analytics will then use the value from the \*event-level\* parameter if one is provided. An item-scoped promotion dimensions for a particular item will only report as "(not set)" if the relevant parameter is missing from \*both\* the item object and the event-level parameters. Item-level parameters always take precedence over event-level parameters.

#### Item parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `item_id` | `string` | **Yes\*** | SKU_12345 | The ID of the item. \*One of `item_id` or `item_name` is required. |
| `item_name` | `string` | **Yes\*** | Stan and Friends Tee | The name of the item. \*One of `item_id` or `item_name` is required. |
| `affiliation` | `string` | No | Google Store | A product affiliation to designate a supplying company or brick and mortar store location. Note: `affiliation` is only available at the item-scope. |
| `coupon` | `string` | No | SUMMER_FUN | The coupon name/code associated with the item. <br /> Event-level and item-level `coupon` parameters are independent. |
| `creative_name` | `string` | No | summer_banner2 | The name of the promotional creative. <br /> Defaults to event-level `creative_name` if not set. |
| `creative_slot` | `string` | No | featured_app_1 | The name of the promotional creative slot associated with the item. <br /> Defaults to event-level `creative_slot` if not set. |
| `discount` | `number` | No | 2.22 | The unit monetary discount value associated with the item. |
| `index` | `number` | No | 5 | The index/position of the item in a list. |
| `item_brand` | `string` | No | Google | The brand of the item. |
| `item_category` | `string` | No | Apparel | The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category. |
| `item_category2` | `string` | No | Adult | The second category hierarchy or additional taxonomy for the item. |
| `item_category3` | `string` | No | Shirts | The third category hierarchy or additional taxonomy for the item. |
| `item_category4` | `string` | No | Crew | The fourth category hierarchy or additional taxonomy for the item. |
| `item_category5` | `string` | No | Short sleeve | The fifth category hierarchy or additional taxonomy for the item. |
| `item_list_id` | `string` | No | related_products | The ID of the list in which the item was presented to the user. <br /> If set, event-level `item_list_id` is ignored. If not set, event-level `item_list_id` is used, if present. |
| `item_list_name` | `string` | No | Related products | The name of the list in which the item was presented to the user. <br /> If set, event-level `item_list_name` is ignored. If not set, event-level `item_list_name` is used, if present. |
| `item_variant` | `string` | No | green | The item variant or unique code or description for additional item details/options. |
| `location_id` | `string` | No | ChIJIQBpAG2ahYAR_6128GcTUEo (the Google Place ID for San Francisco) | The physical location associated with the item (e.g. the physical store location). It's recommended to use the [Google Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) that corresponds to the associated item. A custom location ID can also be used. Note: `location_id` is only available at the item-scope. |
| `price` | `number` | No | 10.01 | The monetary unit price of the item, in units of the specified currency parameter. <br /> If a discount applies to the item, set `price` to the discounted unit price and specify the unit price discount in the `discount` parameter. |
| `promotion_id` | `string` | No | P_12345 | The ID of the promotion associated with the item. <br /> Defaults to event-level `promotion_id` if not set. |
| `promotion_name` | `string` | No | Summer Sale | The name of the promotion associated with the item. <br /> Defaults to event-level `promotion_name` if not set. |
| `quantity` | `number` | No | 3 | Item quantity. <br /> If not set, `quantity` is set to 1. |

In addition to the prescribed parameters, you can include up to 27 [custom parameters](https://developers.google.com/analytics/devguides/collection/ga4/item-scoped-ecommerce) in the `items` array.

#### Example

The following example is for gtag.js implementations:

    gtag("event", "view_promotion", {
      currency: "USD",
      creative_name: "Summer Banner",
      creative_slot: "featured_app_1",
      promotion_id: "P_12345",
      promotion_name: "Summer Sale",
      items: [
        {
          item_id: "SKU_12345",
          item_name: "Stan and Friends Tee",
          affiliation: "Google Merchandise Store",
          coupon: "SUMMER_FUN",
          creative_name: "summer_banner2",
          creative_slot: "featured_app_1",
          discount: 2.22,
          index: 0,
          item_brand: "Google",
          item_category: "Apparel",
          item_category2: "Adult",
          item_category3: "Shirts",
          item_category4: "Crew",
          item_category5: "Short sleeve",
          item_list_id: "related_products",
          item_list_name: "Related Products",
          item_variant: "green",
          location_id: "ChIJIQBpAG2ahYAR_6128GcTUEo",
          price: 10.01,
          promotion_id: "P_12345",
          promotion_name: "Summer Sale",
          google_business_vertical: "retail",
          quantity: 3
        }
      ]
    });

## Games

### `level_end`

This event signifies that a player has reached the end of a level in a game.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `level_name` | `string` | No | The journey begins... | The name of the level. |
| `success` | `boolean` | No | true | Set to `true` if the level was completed successfully. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "level_end", {
      level_name: "The journey begins...",
      success: true
    });

### `level_start`

This event signifies that a player has started a level in a game.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `level_name` | `string` | No | The journey begins... | The name of the level. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "level_start", {
      level_name: "The journey begins..."
    });

### `level_up`

This event signifies that a player has leveled up in a game. Use it to gauge the
level distribution of your user base and identify levels that are difficult to
complete.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `level` | `number` | No | 5 | The level of the character. |
| `character` | `string` | No | Player 1 | The character that leveled up. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "level_up", {
      level: 5,
      character: "Player 1"
    });

### `post_score`

Send this event when the user posts a score. Use this event to understand how
users are performing in your game and correlate high scores with audiences or
behaviors.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `score` | `number` | **Yes** | 10000 | The score to post. |
| `level` | `number` | No | 5 | The level for the score. |
| `character` | `string` | No | Player 1 | The character that achieved the score. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "post_score", {
      score: 10000,
      level: 5,
      character: "Player 1"
    });

### `unlock_achievement`

Log this event when the user has unlocked an achievement. This event can help
you understand how users are experiencing your game.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `achievement_id` | `string` | **Yes** | A_12345 | The id of the achievement that was unlocked. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "unlock_achievement", {
      achievement_id: "A_12345"
    });

## Lead generation

### `close_convert_lead`

Log this event when a qualified lead is successfully converted into a customer.
This typically signifies the end of the lead nurturing process, such as when a
contract is signed, a paid subscription starts, or a final sale is completed.

- **Note:** To track initial lead acquisition, such as form submissions, newsletter sign-ups, or demo requests, use the [`generate_lead`](https://developers.google.com/analytics/devguides/collection/ga4/reference/events#generate_lead) event.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | No | USD | Currency of the value associated with the conversion (such as contract value), in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. Required if `value` is set. |
| `value` | `number` | No | 2500 | The monetary value of the conversion, such as first payment amount or contract value. Required if `currency` is set. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "close_convert_lead", {
      currency: "USD",
      value: 30.03
    });

### `close_unconvert_lead`

This event measures when a user is marked as not becoming a converted lead,
along with the reason.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the `value` of the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `unconvert_lead_reason` | `string` | No | Never responded | The reason the lead was unconverted. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "close_unconvert_lead", {
      currency: "USD",
      value: 30.03,
      unconvert_lead_reason: "Never responded"
    });

### `disqualify_lead`

This event measures when a user is marked as disqualified to become a lead,
along with the reason for the disqualification.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the `value` of the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `disqualified_lead_reason` | `string` | No | Not looking to buy | The reason a lead was marked as disqualified. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "disqualify_lead", {
      currency: "USD",
      value: 30.03,
      disqualified_lead_reason: "Not looking to buy"
    });

### `generate_lead`

This event measures when a lead has been generated (for example, through a
form). Log this to understand the effectiveness of your marketing campaigns and
how many customers re-engage with your business after remarketing to the
customers.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the `value` of the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `lead_source` | `string` | No | Trade show | The source of the lead. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "generate_lead", {
      currency: "USD",
      value: 30.03,
      lead_source: "Trade show"
    });

### `qualify_lead`

This event measures when a user is marked as meeting the criteria to become a
qualified lead.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the `value` of the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "qualify_lead", {
      currency: "USD",
      value: 30.03
    });

### `working_lead`

This event measures when a user contacts or is contacted by a representative.

#### Parameters

| Name | Type | Required | Example value | Description |
|---|---|---|---|---|
| `currency` | `string` | **Yes\*** | USD | Currency of the `value` of the event, in [3-letter ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. <br /> \* If you set `value` then `currency` is required for revenue metrics to be computed accurately. |
| `value` | `number` | **Yes\*** | 30.03 | The monetary value of the event. <br /> \* `value` is typically required for meaningful reporting. If you [mark the event as a key event](https://support.google.com/analytics/answer/9267568) then it's recommended you set `value`. \* `currency` is required if you set `value`. |
| `lead_status` | `string` | No | Started conversations | The status of the lead. |

#### Example

The following example is for gtag.js implementations:

    gtag("event", "working_lead", {
      currency: "USD",
      value: 30.03,
      lead_status: "Started conversations"
    });