# Analytics events in the dataLayer

Event names, payloads and an example checkout flow for embedded Kustom Checkout in an existing dataLayer, with GA4 mapping using GTM.

When analytics is enabled, embedded Kustom Checkout can push funnel events to your page's existing `window.dataLayer`.
Your analytics integration controls where they go; Kustom doesn't forward them to an analytics tool.
The example below uses Google Tag Manager (GTM) and Google Analytics 4 (GA4).

Choose the interface for your task:

| Interface | Use it for |
| --- | --- |
| **dataLayer events** | Checkout funnel reporting through your existing analytics setup |
| [Client-side events](/checkout/client-side-events/) via `api.on()` | Page updates, browser validation or analytics handlers you write yourself |
| [Server-side callbacks](/checkout/callbacks/) | Server-side price and shipping updates, purchase validation and order processing |

## Event overview

| Event | Fires when | Can repeat |
| --- | --- | --- |
| [`begin_checkout`](#begin_checkout) | The checkout loads for the first time for an order | No, once per order |
| [`checkout_first_user_interaction`](#checkout_first_user_interaction) | The customer first clicks or presses a key in the checkout | Once per checkout load; can repeat after a reload |
| [`address_completed`](#address_completed) | The billing address is submitted and accepted, or is prefilled | Yes |
| [`add_shipping_info`](#add_shipping_info) | The customer selects a delivery method | Yes |
| [`add_payment_info`](#add_payment_info) | The customer presses the buy button | Yes |
| [`validation_result`](#validation_result) | Server-side validation returns | Yes |
| [`purchase`](#purchase) | When Checkout first loads the completed order for confirmation | No, once per order |

Use a new order to test `begin_checkout` or `purchase`; neither fires again for the same order.
These are browser signals; use server-side callbacks and the order API for order processing.

### Example checkout flow

This example shows a successful checkout with manual address entry. Event order can vary.

```mermaid
sequenceDiagram
    participant Checkout as Kustom Checkout
    participant Page as Your dataLayer

    critical Customer opens checkout
        Checkout->>Page: begin_checkout
    end

    critical Customer enters their details
        Checkout->>Page: checkout_first_user_interaction
        Checkout->>Page: address_completed
    end

    opt Delivery selection changes
        Checkout->>Page: add_shipping_info
    end

    critical Customer presses Buy
        Checkout->>Page: add_payment_info
    end

    opt Merchant validation runs
        Checkout->>Page: validation_result
        Note over Checkout,Page: result: success
    end

    critical Confirmation loads
        Checkout->>Page: purchase
    end
```

Prefilled addresses can complete before the first interaction. Shipping and validation depend
on your integration, and validation can occur at a different point. Changes and retries can
repeat events as shown in the overview.

## Example: map events to GA4

[GA4 requires `items`](https://developers.google.com/analytics/devguides/collection/ga4/reference/events)
for `begin_checkout`, `add_shipping_info`, `add_payment_info` and `purchase`.
Each item needs `item_id` or `item_name`. Numeric `price` and `quantity` are optional, but
include them for accurate item values and counts. Omitted quantity defaults to `1`.
Kustom's custom events, such as `address_completed`, have no GA4 requirement for `items`.

| Kustom field | GA4 mapping |
| --- | --- |
| `items` | Retain `item_id`, `item_name` and `quantity` for each line. Adjust `price` as below. |
| `items[].price` | Kustom sends tax-inclusive prices before discounts. Use the discounted, tax-exclusive unit price. |
| `value` | Calculate the sum of item price × quantity, excluding tax and shipping. Kustom's value includes both. |
| `currency` | Send at event level whenever you send `value`. |
| `delivery_method` | Map to `shipping_tier` if it represents your shipping tier. |
| `transaction_id` | Retain the unique ID for each purchase. |

Choose one source for each GA4 event if your site already tracks checkout. GA4
[deduplicates web purchases with the same transaction ID](https://support.google.com/analytics/answer/12313109),
but two integrations may use different IDs for one order.

### Forward with GTM

In your existing GTM container, use **Custom Event** triggers to match `event` and **Data Layer
Variables** to read the parameters you need. Pass the mapped values to your **GA4 Event** tag.
Use each event's own fields; values left in GTM's data model by earlier events aren't part
of the current payload.

**Apply consent controls before forwarding.** Send only the fields you need. Don't include
customer-identifying information in order references or other analytics parameters.

## Payload reference

Each push is a flat object with the event name in `event` and parameters beside it.
Kustom pushes these events automatically; don't add a second push.

```js
window.dataLayer.push({
  event: 'address_completed',
  occurred_at: '2026-10-29T11:40:55.801Z',
  country: 'SWE',
  kustom_order_id: 'd6868b5e-151e-2066-971f-3a01fcb3ed54',
  merchant_reference_1: 'EKH42SL362G',
  currency: 'SEK',
  merchant_id: 'M12345678',
  locale: 'sv-SE',
  value: 5033.41,
});
```

### Common parameters

Six events share these parameters: `begin_checkout`, `address_completed`,
`add_shipping_info`, `add_payment_info`, `validation_result` and `purchase`.

| Parameter | Example | Description |
| --- | --- | --- |
| `kustom_order_id` | `d6868b5e-151e-2066-971f-3a01fcb3ed54` | The Kustom order ID |
| `merchant_id` | `M12345678` | Your Kustom merchant ID; the value here is illustrative |
| `merchant_reference_1` | `EKH42SL362G` | Your order reference, when supplied; it can change between events for the same order |
| `country` | `SWE` | Billing country, falling back to the purchase country, as an ISO 3166-1 alpha-3 code |
| `currency` | `SEK` | ISO 4217 currency code |
| `locale` | `sv-SE` | The checkout's locale |
| `value` | `5033.41` | The order total including tax and shipping, as a number in major currency units |
| `occurred_at` | `2026-10-29T11:40:55.801Z` | ISO 8601 timestamp for the event payload |

`address_completed` has no additional parameters. `checkout_first_user_interaction` uses
its own parameter set. Additional fields are listed below.

### E-commerce item data

`begin_checkout`, `add_shipping_info`, `add_payment_info` and `purchase` share an `items`
array. Each item maps these order-line fields:

| Item field | Example | Description |
| --- | --- | --- |
| `item_id` | `Item1` | The order line's `reference` |
| `item_name` | `Item A` | The order line's `name` |
| `price` | `10.01` | Tax-inclusive `unit_price` before discounts, converted to major currency units |
| `quantity` | `1` | The order line's `quantity` |

If `reference` or `name` is absent, `item_id` or `item_name` is omitted.

### begin_checkout

Includes the [common parameters](#common-parameters) and [item data](#e-commerce-item-data).

### checkout_first_user_interaction

This event has no `value` or `items`. Its `country` uses a lowercase alpha-2 code, unlike
the alpha-3 code in the other events. Fields that aren't available yet can be omitted.

| Parameter | Example | Description |
| --- | --- | --- |
| `kustom_order_id` | `d6868b5e-151e-2066-971f-3a01fcb3ed54` | The Kustom order ID, shared with the other events |
| `merchant_id` | `M12345678` | Your Kustom merchant ID |
| `merchant_reference_1` | `EKH42SL362G` | Your first order reference, falling back to your second reference if the first is empty |
| `country` | `se` | Billing country as a lowercase alpha-2 code, when available |
| `currency` | `SEK` | ISO 4217 currency code |
| `locale` | `sv-SE` | The checkout's locale |
| `occurred_at` | `2026-10-29T11:40:41.399Z` | ISO 8601 time the event occurred |

### address_completed

Includes only the [common parameters](#common-parameters).

### add_shipping_info

| Parameter | Example | Description |
| --- | --- | --- |
| `shipping` | `10` | The shipping cost including tax, as a number in major currency units |
| `delivery_method` | `Postnord standard` | The selected delivery method, as a string |

Here `value` includes shipping: `5043.41 = 5033.41 + 10`.

### add_payment_info

| Parameter | Example | Description |
| --- | --- | --- |
| `payment_type` | `paypal` | The payment method, as a string |

### validation_result

| Parameter | Example | Description |
| --- | --- | --- |
| `validation_type` | `server_side` | The check that ran: `server_side` |
| `result` | `success` | The outcome: `success` or `failure` |

### purchase

| Parameter | Example | Description |
| --- | --- | --- |
| `transaction_id` | `d6868b5e-151e-2066-971f-3a01fcb3ed54` | A string with the same value as `kustom_order_id` |
| `payment_type` | `card` | The payment method, as a string |
| `shipping` | `0` | The shipping cost including tax, as a number in major currency units |
| `tax` | `1006.68` | The tax amount, as a number in major units |
| `express` | `false` | Whether the purchase used an express flow, as a boolean |

## Related

- [Checkout JavaScript events](/checkout/client-side-events/): `api.on()` handlers for page
  updates and custom analytics.
- [Server-side callbacks](/checkout/callbacks/): update, validate and process orders on your server.
- [Integration models](/checkout/#integration-models): where the checkout can be rendered.
