Checkout Events

Implement Data Layer events for checkout pages.

Overview

Follow this guide to learn how to implement checkout-related Data Layer events for Agnostic implementations where you control your own checkout pages.

You should push checkout funnel events to the Elevar Data Layer so user actions can be captured, enriched, and forwarded to server-side destinations.

WARNING

Before implementing checkout events, ensure you've completed the Install Scripts guide.

Checkout Funnel Events

Checkout funnel events represent the key steps a user takes during the checkout process. These events should be fired as users progress through your checkout pages.

Event	Description
`dl_begin_checkout`	User initiates the checkout process
`dl_add_shipping_info`	User provides shipping information
`dl_add_payment_info`	User provides payment information
`dl_purchase`	User completes the purchase

INFO

The dl_user_data is a base event that should fire on every page load before other events. See the Push Events guide for implementation details.

Event Examples

This section provides detailed examples for each event type. Examples reference objects and arrays such as products and userProperties.

Use these examples as implementation references. The complete object structures are documented in the Data Examples section below.

Begin Checkout

Fire when a user initiates the checkout process:

javascript

window.ElevarDataLayer.push({
  event: "dl_begin_checkout",
  user_properties: userProperties,
  marketing: {
    landing_site: "/store/product-a?utm_source=web&utm_campaign=spring"
  },
  ecommerce: {
    currencyCode: "USD",
    checkout: {
      actionField: {
        step: "1"
      },
      products: products
    }
  }
});

Important notes:

Fire this event as soon as the checkout page loads or when the checkout flow is initiated.
The marketing.landing_site field should contain the first page path the user landed on when they visited your site with query parameters (UTMs, click IDs).

Add Shipping Info

Fire when a user provides shipping information:

javascript

window.ElevarDataLayer.push({
  event: "dl_add_shipping_info",
  marketing: {
    landing_site: "/store/product-a?utm_source=web&utm_campaign=spring"
  },
  user_properties: userProperties,
  ecommerce: {
    currencyCode: "USD",
    checkout: {
      actionField: {
        step: "2"
      },
      products: products
    }
  }
});

Important notes:

Fire this event when the user fills out the shipping form or navigates to the next page in multi-step checkouts.
The marketing.landing_site field should contain the first page path the user landed on when they visited your site with query parameters (UTMs, click IDs).

Add Payment Info

Fire when a user provides payment information:

javascript

window.ElevarDataLayer.push({
  event: "dl_add_payment_info",
  marketing: {
    landing_site: "/store/product-a?utm_source=web&utm_campaign=spring"
  },
  user_properties: userProperties,
  ecommerce: {
    currencyCode: "USD",
    checkout: {
      actionField: {
        step: "3"
      },
      products: products
    }
  }
});

Important notes:

Fire this event when the user fills out the payment form or navigates to the next page in multi-step checkouts.
The marketing.landing_site field should contain the first page path the user landed on when they visited your site with query parameters (UTMs, click IDs).

Purchase

Fire when a user completes the purchase:

javascript

window.ElevarDataLayer.push({
  event: "dl_purchase",
  marketing: {
    landing_site: "/store/product-a?utm_source=web&utm_campaign=spring"
  },
  user_properties: userProperties,
  ecommerce: {
    currencyCode: "USD",
    purchase: {
      actionField: {
        id: "4835925655784", // Order ID
        order_name: "#1005", // Order User-Friendly ID
        revenue: "185.3", // Revenue
        tax: "15.3",
        shipping: "0.0",
        affiliation: "staging-fully-managed-ga4-all-events", // Store name
        sub_total: "170.0", // Sub total
        product_sub_total: "170.0", // Product Sub total
        discount_amount: "0.0",
        sales_channel: "pos", // Description of sales channel
        physical_location_id: "00000000000" // Location ID of your physical store
      },
      products: products
    }
  }
});

Important notes:

Fire this event only once on the order confirmation page after the order is placed.
The marketing.landing_site field should contain the first page path the user landed on when they visited your site with query parameters (UTMs, click IDs).
The actionField.id should be the unique order ID.
The actionField.revenue should be the total order value including taxes, shipping and discounts.
The actionField.sub_total should be the order subtotal value, including discounts and excluding taxes and shipping.

Data Examples

This section contains the full structure for objects and arrays referenced in the event examples. Use these templates when implementing events in your application by copying the structure and replacing values with your actual product and customer data.

Products Array

javascript

const products = [
  {
    id: "LB00161-34689553170476", // SKU
    name: "Lovebox Original Color & Photo", // Product title
    brand: "Lovebox INC",
    category: "Home,Living,Art & Objects,Tabletop",
    variant: "USA wall plug",
    price: "119.99",
    quantity: "1",
    position: "1", // Position in checkout starting at 1
    list: "/art/wallhangings", // The list the product was discovered from
    product_id: "6979886940352", // The product ID
    variant_id: "41141193965760", // The variant ID
    compare_at_price: "139.99", // If available, otherwise use "0.0"
    image: "//cdn.store.com/small.png", // If available, otherwise use an empty string
    inventory: "5" // If available, otherwise use an empty string
  }
  // ... additional products
];

Important notes:

The list property contains the collection path (e.g., /collections/shoes/) the user came from before taking a particular action on a product page. For example, if a dl_add_to_cart event is pushed, you need to persist the collection path (page URL) the user was on prior to clicking into the product page and taking that action. If the user hasn't seen a collection page at the time of the event, this property can be an empty string.

User Properties Object

javascript

const userProperties = {
  // The following fields aren't required if unavailable
  customer_address_1: "1 Hills Plantation Drive",
  customer_address_2: "",
  customer_city: "Charleston",
  customer_country: "United States",
  customer_email: "bill@gmail.com",
  customer_first_name: "Bill",
  customer_id: "5928549548188",
  customer_last_name: "Call",
  customer_order_count: "1",
  customer_phone: "999-999-9999",
  customer_province: "South Carolina",
  customer_province_code: "SC",
  customer_tags: "",
  customer_total_spent: "0.0",
  customer_zip: "22222",

  // The following fields are required
  user_consent: "", // Use an empty string
  visitor_type: "logged_in" // "logged_in" || "guest"
};

Important notes:

The majority of this information can only be retrieved for a logged in user.
The customer_order_count property determines whether Elevar fires PurchaseNewCustomer or PurchaseReturningCustomer when sending these events to your destinations.

Upsell Purchases

If your checkout includes post-purchase upsell offers between the checkout completion and order confirmation page, you can track these with a dedicated upsell event that fires when a user accepts an upsell offer.

Upsell Purchase

Fire when a user accepts an upsell offer:

javascript

window.dataLayer.push({
  event: "dl_upsell_purchase",
  user_properties: userProperties,
  ecommerce: {
    currencyCode: "USD",
    purchase: {
      actionField: {
        id: "4835925655784-US1", // Original order ID + "-US1"
        order_name: "#1005-US1", // Original order name + "-US1"
        revenue: "29.99", // Upsell revenue only
        tax: "2.50",
        shipping: "0.0",
        affiliation: "staging-fully-managed-ga4-all-events",
        sub_total: "27.49",
        product_sub_total: "27.49",
        discount_amount: "0.0"
      },
      products: products // Upsell products only
    }
  }
});

Important notes:

The dl_upsell_purchase event structure mirrors dl_purchase, but should include only upsell product information, treated as a separate purchase.
Modify the Order ID by adding -US1 suffix for the first upsell, -US2 for the second, etc. This naming convention helps you to track which upsells belong to which original purchase in platforms like GA4.
Fire the original dl_purchase event when the customer reaches the upsell offer page, before they accept or decline. This ensures you capture the initial purchase even if users don't reach the order confirmation page.

INFO

The dl_upsell_purchase event must be pushed to window.dataLayer for GTM to capture it browser-side, as server-side support is not available.

Browser Setup

Headless

Agnostic

Additional Resources

Checkout Events

Overview

Checkout Funnel Events

Event Examples

Data Examples

Upsell Purchases

Checkout Events ​

Overview ​

Checkout Funnel Events ​

Event Examples ​

Data Examples ​

Upsell Purchases ​

Checkout Events

Overview

Checkout Funnel Events

Event Examples

Data Examples

Upsell Purchases