- Checkout
- API reference
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 via api.on() | Page updates, browser validation or analytics handlers you write yourself |
| Server-side callbacks | Server-side price and shipping updates, purchase validation and order processing |
Event overview
Section titled “Event overview”| Event | Fires when | Can repeat |
|---|---|---|
begin_checkout | The checkout loads for the first time for an order | No, once per order |
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 | The billing address is submitted and accepted, or is prefilled | Yes |
add_shipping_info | The customer selects a delivery method | Yes |
add_payment_info | The customer presses the buy button | Yes |
validation_result | Server-side validation returns | Yes |
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
Section titled “Example checkout flow”This example shows a successful checkout with manual address entry. Event order can vary.
- Customer opens checkoutKustom Checkout → Your dataLayerbegin_checkout
- Customer enters their detailsKustom Checkout → Your dataLayercheckout_first_user_interactionKustom Checkout → Your dataLayeraddress_completed
- Delivery selection changes optionalKustom Checkout → Your dataLayeradd_shipping_info
- Customer presses BuyKustom Checkout → Your dataLayeradd_payment_info
- Merchant validation runs optionalKustom Checkout → Your dataLayervalidation_resultresult: success
- Confirmation loadsKustom Checkout → Your dataLayerpurchase
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
Section titled “Example: map events to GA4”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 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, but two integrations may use different IDs for one order.
Forward with GTM
Section titled “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
Section titled “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.
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
Section titled “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
Section titled “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
Section titled “begin_checkout”Includes the common parameters and item data.
checkout_first_user_interaction
Section titled “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
Section titled “address_completed”Includes only the common parameters.
add_shipping_info
Section titled “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
Section titled “add_payment_info”| Parameter | Example | Description |
|---|---|---|
payment_type | paypal | The payment method, as a string |
validation_result
Section titled “validation_result”| Parameter | Example | Description |
|---|---|---|
validation_type | server_side | The check that ran: server_side |
result | success | The outcome: success or failure |
purchase
Section titled “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
Section titled “Related”- Checkout JavaScript events:
api.on()handlers for page updates and custom analytics. - Server-side callbacks: update, validate and process orders on your server.
- Integration models: where the checkout can be rendered.
This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.