---
url: /guides/api/agnostic/checkout-events.md
---
# 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](/guides/api/browser-setup/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](/guides/api/browser-setup/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.

::: details 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).

:::

::: details 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).

:::

::: details 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).

:::

::: details 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.

::: details 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.

:::

::: details 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.

::: details 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.

:::
