Skip to content

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:

InterfaceUse it for
dataLayer eventsCheckout funnel reporting through your existing analytics setup
Client-side events via api.on()Page updates, browser validation or analytics handlers you write yourself
Server-side callbacksServer-side price and shipping updates, purchase validation and order processing
EventFires whenCan repeat
begin_checkoutThe checkout loads for the first time for an orderNo, once per order
checkout_first_user_interactionThe customer first clicks or presses a key in the checkoutOnce per checkout load; can repeat after a reload
address_completedThe billing address is submitted and accepted, or is prefilledYes
add_shipping_infoThe customer selects a delivery methodYes
add_payment_infoThe customer presses the buy buttonYes
validation_resultServer-side validation returnsYes
purchaseWhen Checkout first loads the completed order for confirmationNo, 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.

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

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.

GA4 requires items 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 fieldGA4 mapping
itemsRetain item_id, item_name and quantity for each line. Adjust price as below.
items[].priceKustom sends tax-inclusive prices before discounts. Use the discounted, tax-exclusive unit price.
valueCalculate the sum of item price × quantity, excluding tax and shipping. Kustom’s value includes both.
currencySend at event level whenever you send value.
delivery_methodMap to shipping_tier if it represents your shipping tier.
transaction_idRetain 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, but two integrations may use different IDs for one order.

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.

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.

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,
});

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

ParameterExampleDescription
kustom_order_idd6868b5e-151e-2066-971f-3a01fcb3ed54The Kustom order ID
merchant_idM12345678Your Kustom merchant ID; the value here is illustrative
merchant_reference_1EKH42SL362GYour order reference, when supplied; it can change between events for the same order
countrySWEBilling country, falling back to the purchase country, as an ISO 3166-1 alpha-3 code
currencySEKISO 4217 currency code
localesv-SEThe checkout’s locale
value5033.41The order total including tax and shipping, as a number in major currency units
occurred_at2026-10-29T11:40:55.801ZISO 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.

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

Item fieldExampleDescription
item_idItem1The order line’s reference
item_nameItem AThe order line’s name
price10.01Tax-inclusive unit_price before discounts, converted to major currency units
quantity1The order line’s quantity

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

Includes the common parameters and item data.

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.

ParameterExampleDescription
kustom_order_idd6868b5e-151e-2066-971f-3a01fcb3ed54The Kustom order ID, shared with the other events
merchant_idM12345678Your Kustom merchant ID
merchant_reference_1EKH42SL362GYour first order reference, falling back to your second reference if the first is empty
countryseBilling country as a lowercase alpha-2 code, when available
currencySEKISO 4217 currency code
localesv-SEThe checkout’s locale
occurred_at2026-10-29T11:40:41.399ZISO 8601 time the event occurred

Includes only the common parameters.

ParameterExampleDescription
shipping10The shipping cost including tax, as a number in major currency units
delivery_methodPostnord standardThe selected delivery method, as a string

Here value includes shipping: 5043.41 = 5033.41 + 10.

ParameterExampleDescription
payment_typepaypalThe payment method, as a string
ParameterExampleDescription
validation_typeserver_sideThe check that ran: server_side
resultsuccessThe outcome: success or failure
ParameterExampleDescription
transaction_idd6868b5e-151e-2066-971f-3a01fcb3ed54A string with the same value as kustom_order_id
payment_typecardThe payment method, as a string
shipping0The shipping cost including tax, as a number in major currency units
tax1006.68The tax amount, as a number in major units
expressfalseWhether the purchase used an express flow, as a boolean

This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.