Advanced Checkout Events

Global‑e Checkout Analytics enables merchants to track and analyze detailed checkout-related activities by integrating with their analytics platforms. Merchants can listen to Advanced Checkout Events in their code and trigger custom events based on customer interactions. Unlike standard checkout events, which only capture key milestones like checkout started and purchase confirmation, Advanced Checkout Events provide a deeper level of tracking. These events allow merchants to monitor additional actions within the checkout flow, such as form interactions, selection changes, error messages, and engagement with on-page elements. By leveraging these events, merchants gain richer insights into shopper behavior, helping them optimize the checkout experience and reduce friction.

Business Events

Business Events help merchants identify trends, optimize checkout flows, and troubleshoot issues that may prevent successful order completion.

ADD_NEW_SHIPPING_ADDRESS

Show details

This event is triggered when a customer chooses to provide a shipping address that is different from the billing address during the checkout process. It signals the start of entering a new shipping address and reflects the customer’s decision to separate shipping and billing details.This event does not include any data or payload.Examples

POST {globale domain}/Return/GetReturnDocuments

BILLING_ADDRESS_COMPLETED

Show details

This event is triggered when a user completes and successfully validates all required billing address fields during the checkout process. It ensures that the billing information is fully entered and meets the necessary validation criteria.Examples of mandatory fields:

First Name: The first name of the person being billed (e.g., “John”).
Last Name: The last name of the person being billed (e.g., “Doe”).
Address: The full street address (e.g., “123 Main St, Apartment 4B”).
Phone Number: A valid contact number (e.g., “+1-123-456-7890”).

This event does not include any data or payload.Examples

// Subscribe to the BILLING_ADDRESS_COMPLETED event
var glegem = glegem || function() {
    ((window["glegem"] = window["glegem"] || {q:[]}).q = window["glegem"].q || []).push(arguments);
};
glegem("OnClientEvent", function (source) {
    if (source === GEMerchantUtils.ClientEvents.BILLING_ADDRESS_COMPLETED) {
        console.log("Event: BILLING_ADDRESS_COMPLETED"); // No additional data provided
    }
});

CHECKOUT_FAILURE

Show details

This event is triggered when an issue occurs during the checkout process, ranging from minor errors to critical blockages that prevent the customer from completing their purchase. Examples include product restrictions for a specific country, payment validation failures, or exceeding allowable weight limits for shipping.

failureCode: Indicates the type of issue that occurred during the checkout process. Possible values include:
- RestrictedProducts: Products in the cart are restricted in the selected shipping country.
- UpdateShippingCountryFailed: The shipping country could not be updated successfully.
- NoShippingOptions: No shipping options are available for the selected address.
- DutyThresholdOverFormalClearance: The order exceeds the duty threshold requiring formal clearance.
- PaymentDeclined: The payment method was declined.
- TechnicalError: A technical error occurred during the checkout process.
- SessionExpired: The checkout session expired before completion.
- NoPrepayForceDDP: Prepayment of duties and taxes is not available for the order.
- CartValidation: The cart failed validation checks.
- CouponAmountTooLow: The applied coupon amount is below the required minimum value.
reasonCode: Provides additional details about the specific failure, if available. This property may be null in some cases.

Examples

// Subscribe to the CHECKOUT_FAILURE event
var glegem = glegem || function() {
    ((window["glegem"] = window["glegem"] || {q:[]}).q = window["glegem"].q || []).push(arguments);
};
glegem("OnClientEvent", function (source, data) {
    if (source === GEMerchantUtils.ClientEvents.CHECKOUT_FAILURE) {
        console.log("Event: CHECKOUT_FAILURE");
        // Handle the 'failureCode' property
        if (data.failureCode) {
            console.log(`Failure Code: ${data.failureCode}`);
            switch (data.failureCode) {
                case "RestrictedProducts":
                    console.log("Reason: Products are restricted in the selected shipping country.");
                    break;
                case "UpdateShippingCountryFailed":
                    console.log("Reason: Failed to update the shipping country.");
                    break;
                case "NoShippingOptions":
                    console.log("Reason: No shipping options are available for the selected address.");
                    break;
                case "DutyThresholdOverFormalClearance":
                    console.log("Reason: Order exceeds the duty threshold requiring formal clearance.");
                    break;
                case "PaymentDeclined":
                    console.log("Reason: Payment was declined.");
                    break;
                case "TechnicalError":
                    console.log("Reason: A technical error occurred during checkout.");
                    break;
                case "SessionExpired":
                    console.log("Reason: The checkout session expired.");
                    break;
                case "NoPrepayForceDDP":
                    console.log("Reason: Prepayment of duties and taxes is not available for this order.");
                    break;
                case "CartValidation":
                    console.log("Reason: The cart failed validation checks.");
                    break;
                case "CouponAmountTooLow":
                    console.log("Reason: Applied coupon amount is below the required minimum.");
                    break;
                default:
                    console.log("Reason: Unknown failure code.");
            }
        }
        // Handle the 'reasonCode' property, if available
        if (data.reasonCode) {
            console.log(`Reason Code: ${data.reasonCode}`);
        } else {
            console.log("No additional reason code provided.");
        }
    }
});

PAYMENTMETHOD_CHANGED

Show details

This event is triggered when a customer selects or changes their payment method during checkout. For credit cards, the event is fired as soon as the card type (e.g., Visa, Mastercard) is recognized while the customer is typing their card details. For alternative payment methods, such as PayPal, the event is triggered when the customer selects or switches to a different payment option.The PAYMENTMETHOD_CHANGED event provides information about the payment method selected by the customer:

id: Specifies the unique identifier of the selected payment method.
name: Specifies the name of the selected payment method. Examples:
- PayPal: When the customer selects PayPalas the payment method.
- Visa: When the customer selects Visaas the payment method.
- ApplePay: When the customer selects ApplePayas the payment method.

Examples

// Subscribe to the PAYMENTMETHOD_CHANGED event
var glegem = glegem || function() {
    ((window["glegem"] = window["glegem"] || {q:[]}).q = window["glegem"].q || []).push(arguments);
};
glegem("OnClientEvent", function (source, data) {
    if (source === GEMerchantUtils.ClientEvents.PAYMENTMETHOD_CHANGED) {
        console.log("Event: PAYMENTMETHOD_CHANGED");
        // Print the payment method name and ID
        if (data.id && data.name) {
            console.log(`Payment Method Selected: ${data.name} (ID: ${data.id})`);
        }
    }
});

Implementation Tips and Best PracticesThe PAYMENTMETHOD_CHANGEDevent does not capture clicks on express payment methods, such as Apple Pay or Google Pay. These methods often bypass the standard payment selection process, and their interactions may need to be tracked separately through DOM events or platform-specific integrations.

SHIPPING_ADDRESS_COMPLETED

Show details

This event is triggered when a user completes and successfully validates all required shipping address fields during the checkout process. It indicates that the shipping information is fully entered, verified, and ready for the next step. The event accounts for different scenarios, including when the shipping address matches the billing address or when alternative options are selected.Examples of mandatory fields:

First Name: The first name of the recipient (e.g., “Jane”).
Last Name: The last name of the recipient (e.g., “Smith”).
Address: The full shipping address (e.g., “456 Elm St, Suite 5”).
Phone Number: A valid contact number for delivery (e.g., “+1-987-654-3210”).

The event also provides information about the type of shipping address selected by the shopper:

ShippingAddressType: Specifies the type of shipping address. Possible values:
- SameAsBilling: When the shipping and billing addresses are the same, and the billing details are completed.
- Alternative: When the shopper chooses a shipping address different from the billing address.
- Store: When the shopper selects a store pickup option and confirms the store. (Optional feature)
- CollectionPoint: When the shopper selects and confirms a collection point. (Optional feature)

Examples

// Subscribe to the SHIPPING_ADDRESS_COMPLETED event
var glegem = glegem || function() {
    ((window["glegem"] = window["glegem"] || {q:[]}).q = window["glegem"].q || []).push(arguments);
};
glegem("OnClientEvent", function (source, data) {
    if (source === GEMerchantUtils.ClientEvents.SHIPPING_ADDRESS_COMPLETED) {
        console.log("Event: SHIPPING_ADDRESS_COMPLETED");
        // Handle the specific ShippingAddressType values
        if (data.ShippingAddressType === "SameAsBilling") {
            console.log("Shipping Address Type: Same as Billing Address");
        } else if (data.ShippingAddressType === "Alternative") {
            console.log("Shipping Address Type: Alternative Address Selected");
        } else if (data.ShippingAddressType === "Store") {
            console.log("Shipping Address Type: Store Pickup Selected");
        } else if (data.ShippingAddressType === "CollectionPoint") {
            console.log("Shipping Address Type: Collection Point Selected");
        }
    }
});// Subscribe to the BILLING_ADDRESS_COMPLETED event
var glegem = glegem || function() {
    ((window["glegem"] = window["glegem"] || {q:[]}).q = window["glegem"].q || []).push(arguments);
};
glegem("OnClientEvent", function (source) {
    if (source === GEMerchantUtils.ClientEvents.BILLING_ADDRESS_COMPLETED) {
        console.log("Event: BILLING_ADDRESS_COMPLETED"); // No additional data provided
    }
});

Implementation Tips and Best Practices

This event is usually mapped to add_shipping_info in Google Analytics 4 (GA4) or equivalent events in other analytics platforms. It represents a key milestone in the checkout process, indicating that the user has provided their shipping information.
In the Global-e checkout, the order of forms can vary based on the setup. The billing form might appear before the shipping form. When the billing address is completed, it will also trigger the SHIPPING_ADDRESS_COMPLETEDevent with SameAsBillingas the default, since billing and shipping are marked as the same by default. If the shopper chooses a different shipping address, the SHIPPING_ADDRESS_COMPLETEDevent will fire again, this time with Alternativeas the value for ShippingAddressType.

SHIPPINGMETHOD_SELECTION

Show details

This event is triggered when a customer selects a shipping method during the checkout process. It indicates that the customer has chosen their preferred shipping option.The SHIPPINGMETHOD_SELECTION event provides detailed information about the selected shipping method.

id: Specifies the element ID of the selected shipping option. Example: def-ship-opt-2-10000388.opt
- opt-2: Indicates the user selected the second shipping option.
- 10000388: Represents the unique identifier for the selected shipping method.
price: Specifies the cost of the selected shipping method, including the currency symbol. Example: $ 7.00.

These properties enable precise tracking of the shipping method chosen by the customer, allowing businesses to analyze preferences and calculate costs effectively.Examples

// Subscribe to the SHIPPINGMETHOD_SELECTION event
var glegem = glegem || function() {
    ((window["glegem"] = window["glegem"] || {q:[]}).q = window["glegem"].q || []).push(arguments);
};
glegem("OnClientEvent", function (source, data) {
    if (source === GEMerchantUtils.ClientEvents.SHIPPINGMETHOD_SELECTION) {
        console.log("Event: SHIPPINGMETHOD_SELECTION");
        // Access and log the 'id' property
        if (data.id) {
            console.log("Selected Shipping Option ID:", data.id);
            // Extract and log the option number and shipping method ID
            const optionMatch = data.id.match(/opt-(\d+)/);
            const methodIdMatch = data.id.match(/(\d+)$/);
            if (optionMatch) {
                console.log("Selected Option Number:", optionMatch[1]);
            }
            if (methodIdMatch) {
                console.log("Shipping Method ID:", methodIdMatch[1]);
            }
        }
        // Access and log the 'price' property
        if (data.price) {
            console.log("Shipping Price:", data.price);
        }
    }
});

STORE_SELECTION

Show details

This event is triggered when a shopper selects a store collection option during the checkout process. It signals that the customer has chosen to pick up their order from a designated store location instead of opting for delivery.This event does not include any data or payload.Examples

// Subscribe to the STORE_SELECTION event
var glegem = glegem || function() {
    ((window["glegem"] = window["glegem"] || {q:[]}).q = window["glegem"].q || []).push(arguments);
};
glegem("OnClientEvent", function (source) {
    if (source === GEMerchantUtils.ClientEvents.STORE_SELECTION) {
        console.log("Event: STORE_SELECTION"); // No additional data provided
    }
});

Implementation Tips and Best PracticesThe store collection feature is an optional capability and is not available for all merchants by default. Merchants need to enable this feature explicitly for it to be offered as a shipping option.

TAX_OPTION_SELECTED

Show details

This event is triggered when the customer selects their preferred option for paying duties and taxes during the checkout process. It occurs when the customer chooses between:

Paying duties and taxes at checkout: The customer opts to prepay duties and taxes as part of their order total.
Paying duties and taxes upon delivery: The customer decides to pay duties and taxes directly to the carrier or customs upon receiving the shipment.

The TAX_OPTION_SELECTEDevent provides information about the customer’s choice for handling duties and taxes during checkout:

id: Specifies the selected tax payment option.
- Possible values:
  - IncludeInOrder: Indicates the customer has chosen to prepay duties and taxes as part of their order total.
  - ManualPay: A valid contact number (e.g., “+1-123-456-7890”).
- Examples:
  - IncludeInOrder: The customer chooses to pay duties and taxes during checkout.
  - ManualPay: The customer opts to pay duties and taxes when the shipment is delivered.

Examples

// Subscribe to the TAX_OPTION_SELECTED event
var glegem = glegem || function() {
    ((window["glegem"] = window["glegem"] || {q:[]}).q = window["glegem"].q || []).push(arguments);
};
glegem("OnClientEvent", function (source, data) {
    if (source === GEMerchantUtils.ClientEvents.TAX_OPTION_SELECTED) {
        console.log("Event: TAX_OPTION_SELECTED");
        // Handle the 'id' property
        if (data.id === "IncludeInOrder") {
            console.log("Tax Option: Include in Order - Duties and taxes will be paid at checkout.");
        } else if (data.id === "ManualPay") {
            console.log("Tax Option: Manual Pay - Duties and taxes will be paid upon delivery.");
        }
    }
});

Implementation Tips and Best PracticesThere are scenarios where this event may not be triggered. For example, if the shopper proceeds with the default option (paying duties and taxes within the checkout) without making any changes, the event won’t fire. Additionally, in cases where the country’s duties and taxes configuration is set to “Hidden Force DDP,” meaning that duties and taxes are already included in the product prices, this event will not be triggered. Similarly, if the total value of the checkout falls below the country’s tax threshold, or if the country does not impose duties and taxes at all, the event will not occur. These situations ensure the event is only sent when a manual selection of tax payment options is required and applied by the shopper.

EXPRESS_PAYMENT_SELECTED

Show details

This event is triggered when a shopper selects an express payment method during the checkout process, such as Apple Pay or Google Pay.The event includes the following data:

id: Specifies the Global-e internal payment method ID of the selected express payment method. Example: 135.
name: Specifies the name of the express payment method. Example: ApplePay Express.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.EXPRESS_PAYMENT_SELECTED) {
    console.log("Express payment selected:", data.id, data.name);
  }
});

LANGUAGE_CHANGED

Show details

This event is triggered when a shopper changes the language during checkout.The event includes the following data:

FromLanguage: Specifies the previous language, as a culture code — e.g. en-US.
ToLanguage: Specifies the newly selected language, as a culture code — e.g. fr-FR.
ShippingCountry: Specifies the shipping country, as an ISO2 country code.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.LANGUAGE_CHANGED) {
    console.log("Language changed from", data.FromLanguage, "to", data.ToLanguage);
  }
});

ADD_NEW_BILLING_ADDRESS

Show details

This event is triggered when the shopper chooses to enter a billing address that differs from the shipping address. It signals the start of the separate billing address entry process.This event does not include any data or payload.Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.ADD_NEW_BILLING_ADDRESS) {
    // Shopper started entering a billing address separate from shipping.
    console.log("Add new billing address");
  }
});

STORE_LOCATION_SELECTED

Show details

This event is triggered when the shopper selects and confirms a specific store as the delivery location in the ship-to-store flow. It occurs after the Store Selection event, once an individual store has been selected.The event includes the following data:

storeData: Specifies the selected store details as a JSON-stringified object. Use JSON.parse() to convert it into a JavaScript object.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.STORE_LOCATION_SELECTED) {
    const store = JSON.parse(data.storeData);
    console.log("Selected store:", store);
    console.log("Cart token:", data.cartToken);
  }
});

COLLECTION_POINT_SELECTED

Show details

This event is triggered when the shopper selects and confirms a collection point as the delivery location, choosing to collect the order from a designated location.The event includes the following data:

collectionPointData: Specifies the selected collection point details as a JSON-stringified object. Use JSON.parse() to convert it into a JavaScript object.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.COLLECTION_POINT_SELECTED) {
    const collectionPoint = JSON.parse(data.collectionPointData);
    console.log("Selected collection point:", collectionPoint);
    console.log("Cart token:", data.cartToken);
  }
});

PAYMENT_DISCOUNT_DISPLAY

Show details

This event is triggered when the checkout is initialized and a payment-method discount is available for display to the shopper.The event includes the following data:

PaymentDiscountCouponData: Specifies the details of the available payment-method discount. It contains:
- CouponName — Specifies the name of the payment-method discount coupon.
- PaymentMethodId — Specifies the payment method ID to which the discount applies.
- PaymentMethodName — Specifies the name of the payment method to which the discount applies.
- BINs — Specifies the eligible card BIN ranges for the discount.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.PAYMENT_DISCOUNT_DISPLAY) {
    console.log("Payment discount available:", data.PaymentDiscountCouponData.CouponName);
  }
});

PAYMENT_DISCOUNT_MISMATCH

Show details

This event is triggered when the card BIN entered by the shopper does not match the BINs eligible for the payment-method discount. As a result, the discount is not applied.The event includes the following data:

PaymentDiscountCouponData: Specifies the details of the mismatch. It contains:
- Reason — Specifies why the entered card BIN did not match the discount’s eligible BINs.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.PAYMENT_DISCOUNT_MISMATCH) {
    console.log("Discount did not match:", data.PaymentDiscountCouponData.Reason);
  }
});

COMPLETE_WITH_DISCOUNT

Show details

This event is triggered when the shopper clicks “Pay” while an eligible payment-method discount is active, indicating that the order is being completed with the discount applied.The event includes the following data:

PaymentDiscountCouponData: Details of the applied discount. Contains:
- Coupon — Specifies the payment-method discount coupon being applied.
- PaymentMethodId — Specifies the payment method ID to which the discount applies.
- PaymentMethodName — Specifies the name of the payment method to which the discount applies.
- BIN — Specifies the matched card BIN.
- BINs — Specifies the eligible card BIN ranges for the discount.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.COMPLETE_WITH_DISCOUNT) {
    console.log("Completing with discount:", data.PaymentDiscountCouponData.Coupon);
  }
});

ON_CLIENT_ERROR

Show details

This event is triggered when a client-side JavaScript error occurs during the checkout.The event includes the following data:

message: Specifies the error message.
url: Specifies the URL where the error occurred.
lineNumber: Specifies the line number where the error occurred.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.ON_CLIENT_ERROR) {
    console.log("Client error:", data.message, "at", data.url, data.lineNumber);
  }
});

ON_SERVER_ERROR

Show details

This event is triggered when a server-side error occurs during checkout.The event includes the following data:

process: Specifies the process in which the error occurred.
error: Specifies the error details.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.ON_SERVER_ERROR) {
    console.log("Server error in", data.process, ":", data.error);
  }
});

WINDOW_SHOWN

Show details

This event is triggered when a popup or modal window is displayed, such as the Address Verification popup.The event includes the following data:

id: Specifies the identifier of the popup — e.g. AddressVerificationPopup.
tag: Specifies the popup tag — e.g. POPUP.
text: Specifies the display text associated with the event — e.g. Address Verification Popup is shown.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.WINDOW_SHOWN) {
    console.log("Window shown:", data.id);
  }
});

LOYALTY_CREDIT_BALANCE_INPUT_MANUALLY_CHANGED

Show details

This event is triggered when a shopper manually edits the loyalty-credit amount input field — for example typing or adjusting the credit value they want to use.The LOYALTY_CREDIT_BALANCE_INPUT_MANUALLY_CHANGED event provides the following data:

id: Specifies the identifier of the loyalty-credit input.
name: Specifies the name of the loyalty-credit input.
amount: Specifies the entered credit amount.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.LOYALTY_CREDIT_BALANCE_INPUT_MANUALLY_CHANGED) {
    console.log("Loyalty credit input changed to", data.amount);
  }
});

LOYALTY_CREDIT_BALANCE_CHANGED

Show details

This event is triggered when a shopper amends the loyalty-credit balance — the amend balance action in the loyalty credit widget.The LOYALTY_CREDIT_BALANCE_CHANGED event provides the following data:

id: Specifies the identifier of the loyalty-credit input.
name: Specifies the name of the loyalty-credit input.
amount: Specifies the entered credit amount.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.LOYALTY_CREDIT_BALANCE_CHANGED) {
    console.log("Loyalty balance amended:", data.amount);
  }
});

LOYALTY_CREDIT_BALANCE_APPLIED

Show details

This event is triggered when a shopper applies loyalty credit to the order — the apply action in the loyalty credit widget.The LOYALTY_CREDIT_BALANCE_APPLIED event provides the following data:

id: Specifies the identifier of the loyalty-credit element.
name: Specifies the name of the loyalty-credit element.
amount: Specifies the applied credit amount.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.LOYALTY_CREDIT_BALANCE_APPLIED) {
    console.log("Loyalty credit applied:", data.amount);
  }
});

DUTIES_AND_TAXES_CALCULATED

Show details

This event is triggered when duties and taxes (or sales tax / local taxes) are calculated and become visible on the checkout, and their amount is greater than zero. It is not triggered when no duties and taxes are displayed, when the amount is 0, or in ForceDDP / hidden duties-and-taxes scenarios.The DUTIES_AND_TAXES_CALCULATED event provides the following data:

type: Specifies the type of taxes calculated — e.g. International Duties and Taxes or Sales Tax.
amount: Specifies the amount of taxes calculated for the checkout — e.g. 42.3.
currency: Specifies the currency in which the shopper sees the duties and taxes — e.g. USD.
optional_to_pay: Specifies whether the shopper can pay the duties and taxes later, or must pay them within the checkout — true or false.
country: Specifies the shipping country, as an ISO2 country code — e.g. US.

Examples

glegem("OnClientEvent", function (source, data) {
  if (source === GEMerchantUtils.ClientEvents.DUTIES_AND_TAXES_CALCULATED) {
    console.log("Duties and taxes calculated:", data.type, data.amount, data.currency);
    console.log("Optional to pay:", data.optional_to_pay, "Country:", data.country);
  }
});

Data Object Model Events

Data Object Model (DOM) Events track direct customer interactions with elements on the checkout page. These events help Merchants to optimize the user experience, reduce friction in forms, and increase checkout completion rates.

BUTTON_CLICKED

Show details

This event is triggered when a customer clicks a button during the checkout. It captures details about the button interaction, including its purpose and outcome. For Pay or Apply Coupon buttons, it provides additional data on payment or coupon code validation results.The BUTTON_CLICKED event provides details about the button that was interacted with:

id: The unique identifier of the button element. Example: “PayButton”.
tag: The HTML tag name of the button. Example: “BUTTON”.
text: The visible text displayed on the button. Example: “Pay and place order”.
action: A description of the button’s function. Example: “Pay”.
success: Indicates whether the action was successful (true) or failed (false). Example: false(the payment attempt failed due to validation errors).
error: If success is false, this field provides details about the failure reason. Example: “CheckoutFormValidationFailed” (the checkout form contains missing or invalid fields).
errorFields: If applicable, lists the specific form fields that caused the validation failure. Example: “CheckoutData_BillingFirstName,CheckoutData_BillingLastName,CheckoutData_BillingAddress1,BillingCity,BillingCountyID,BillingZIP,CheckoutData_BillingPhone”.

Examples

// Subscribe to the BUTTON_CLICKED event
var glegem = glegem || function() {
    ((window["glegem"] = window["glegem"] || {q:[]}).q = window["glegem"].q || []).push(arguments);
};
glegem("OnClientEvent", function (source, data) {
    if (source === GEMerchantUtils.ClientEvents.BUTTON_CLICKED) {
        console.log("Event: BUTTON_CLICKED");
        // Log button details
        console.log(`Button ID: ${data.id}`);
        console.log(`Text: ${data.text}`);
        console.log(`Action: ${data.action}`);
        // Handle standard payment button
        if (data.action === "Pay") {
            if (data.success) {
                console.log("Payment Successful.");
            } else {
                console.log("Payment Failed.");
                console.log(`Error: ${data.error}`);
                if (data.errorFields) {
                    console.log("Validation Errors in Fields:", data.errorFields);
                }
            }
        }
        // Handle express payment methods
        if (data.action === "Express Payment button clicked") {
            console.log(`Express Payment Method Selected: ${data.name}`);
        }
    }
});

Implementation Tips and Best PracticesThe BUTTON_CLICKEDevent tracks when a customer initiates a payment by clicking the Paybutton. However, this event does not capture interactions with express payment methods, such as Apple Pay or PayPal Express, which may bypass the standard checkout flow.For express payment methods, the event can trigger with an action value is “Express Payment button clicked”. If tracking express payments is necessary, consider implementing additional event listeners specifically for these buttons to ensure full coverage of all payment methods.

CHECKBOX_CHANGE

Show details

This event is triggered when a customer interacts with a checkbox within the checkout. It captures when a checkbox is clicked and whether it is checked or unchecked. This event is useful for tracking user preferences, such as opting in for promotional emails or agreeing to terms and conditions.The event provides details about the checkbox that was interacted with:

id: The unique identifier of the checkbox element. Example: “CheckoutData_OffersFromMerchant”.
name: The name attribute of the checkbox element. Example: “CheckoutData.OffersFromMerchant”.
checked: Indicates whether the checkbox is selected (true) or deselected (false). Example: true(the customer opted in to receive offers from the merchant).

Note: The example above refers to a checkbox where the customer can opt in to receive promotional offers from the merchant.Examples

// Subscribe to the CHECKBOX_CHANGE event
var glegem = glegem || function() {
    ((window["glegem"] = window["glegem"] || {q:[]}).q = window["glegem"].q || []).push(arguments);
};
glegem("OnClientEvent", function (source, data) {
    if (source === GEMerchantUtils.ClientEvents.CHECKBOX_CHANGE) {
        console.log("Event: CHECKBOX_CHANGE");
        // Log checkbox details
        console.log(`Checkbox ID: ${data.id}`);
        console.log(`Checkbox Name: ${data.name}`);
        console.log(`Checked: ${data.checked}`);
        // Specific handling for merchant offers checkbox
        if (data.id === "CheckoutData_OffersFromMerchant" || data.name === "CheckoutData.OffersFromMerchant") {
            if (data.checked) {
                console.log("User opted in to receive offers from the merchant.");
            } else {
                console.log("User opted out of receiving offers from the merchant.");
            }
        }
    }
});

Implementation Tips and Best PracticesThe CHECKBOX_CHANGEevent can be used with Klaviyo or similar tools to track marketing opt-in preferences. If you’re using the INPUT_BLUR event for customer identification, make sure to capture the checkbox status before sending data to the platform. This ensures that marketing emails are only sent to users who have explicitly opted in. Refer to the INPUT_BLURevent for tracking email input fields.

COMBO_CHANGED

Show details

This event is triggered when a customer selects or changes a value in a dropdown (select list) during checkout. It helps track user interactions with selectable options, such as choosing a country, state, county, etc.The event provides details about the element that was interacted with:

id: The unique identifier of the select list or radio button element. Example: “BillingCountyID”.
name: The name attribute of the element. Example: “CheckoutData.BillingCountyID”.
text: The visible text of the selected option. Example: “Clare”.
value: The underlying value associated with the selected option. Example: “5”.

Examples

// Subscribe to the COMBO_CHANGED event
var glegem = glegem || function() {
    ((window["glegem"] = window["glegem"] || {q:[]}).q = window["glegem"].q || []).push(arguments);
};
glegem("OnClientEvent", function (source, data) {
    if (source === GEMerchantUtils.ClientEvents.COMBO_CHANGED) {
        console.log("Event: COMBO_CHANGED");
        // Log dropdown or radio button details
        console.log(`Element ID: ${data.id}`);
        console.log(`Element Name: ${data.name}`);
        console.log(`Selected Text: ${data.text}`);
        console.log(`Selected Value: ${data.value}`);
    }
});

INPUT_BLUR

Show details

This event is triggered when a customer moves out of (or “unfocuses”) a text input field after entering or interacting with it. It helps track how users engage with form fields during checkout, providing insights into input behavior and potential friction points.The event includes details about the input field the customer was interacting with:

id: The unique identifier of the input field. Example: “CheckoutData_Email”.
name: The name attribute of the input field. Example: “CheckoutData.Email”.
value: The text entered by the customer before leaving the field. Example: “example@global-e.com”.

Note: The example above refers to the billing email address field in the checkout form.Examples

// Subscribe to the STORE_SELECTION event
var glegem = glegem || function() {
    ((window["glegem"] = window["glegem"] || {q:[]}).q = window["glegem"].q || []).push(arguments);
};
glegem("OnClientEvent", function (source) {
    if (source === GEMerchantUtils.ClientEvents.STORE_SELECTION) {
        console.log("Event: STORE_SELECTION"); // No additional data provided
    }
});

Implementation Tips and Best PracticesThis INPUT_BLURevent can be used with Klaviyo or similar tools to trigger an identification action. However, ensure that you capture the marketing opt-in checkbox value before sending data to the platform to prevent sending emails without the user’s consent. Refer to CHECKBOX_CHANGE event.

Examples of Use in DOM Events

The following examples show how to use DOM Events to detect common checkout actions.

add_payment_info

Show details

Trigger: This event is triggered when a shopper completes the required payment information, for example, after returning from PayPal or completing the required credit card fields.Example

glegem("OnClientEvent", function (source, data) {
    switch (source) {
        case GEMerchantUtils.ClientEvents.INPUT_BLUR:
            if (data && (data.id === "cardNum" || data.id === "cvdNumber")) {
                /*your code*/
            }
            break;
        case GEMerchantUtils.ClientEvents.COMBO_CHANGED:
            if (data && (data.id === "cardExpiryMonth" || data.id === "cardExpiryYear")) {
                /*your code*/
            }
            break;
    }
});

place_order

Show details

Trigger: This event is triggered when a shopper clicks the “Pay Securely Now” button and attempts to place an order.Example

glegem("OnClientEvent", function (source, data) {
    switch (source) {
        case GEMerchantUtils.ClientEvents.BUTTON_CLICKED:
            if (data.action === "Pay") {
                /*your code*/
            }
            break;
    }
});

add_giftcard

Show details

Trigger: This event is triggered when a shopper enables the option to use a gift card.Example

glegem("OnClientEvent", function (source, data) {
    switch (source) {
        case GEMerchantUtils.ClientEvents.CHECKBOX_CHANGE:
            if (data && data.checked === true && data.id === "pay-with-gift-card-toggle") {
                /*your code*/
            }
            break;
    }
});

giftcard_apply

Show details

Trigger: This event is triggered each time a shopper applies a gift card to the order.Example

glegem("OnClientEvent", function (source, data) {
    switch (source) {
        case GEMerchantUtils.ClientEvents.BUTTON_CLICKED:
            if (data.id === "ApplyGiftCard") {
                /*your code*/
            }
            break;
    }
});

giftcard_check_balance

Show details

Trigger: This event is triggered when a shopper enters the gift card details and clicks the “Check Available Balance” button.Example

glegem("OnClientEvent", function (source, data) {
    switch (source) {
        case GEMerchantUtils.ClientEvents.BUTTON_CLICKED:
            if (data.id === "ValidateGiftCard") {
                /*your code*/
            }
            break;
    }
});

select_payment

Show details

Trigger: This event is triggered when a shopper selects an express checkout or payment method, such as PayPal Quick Checkout or PayPal, or begins entering their credit card details.Example

glegem("OnClientEvent", function (source, data) {
    switch (source) {
        case GEMerchantUtils.ClientEvents.BUTTON_CLICKED:
            if (data.id === "paypal-button") {
                /*your code*/
            }
            break;
    }
});

add_rewards

Show details

Trigger: This event is triggered when a shopper selects the toggle to use their rewards balance.Example

glegem("OnClientEvent", function (source, data) {
    switch (source) {
        case GEMerchantUtils.ClientEvents.CHECKBOX_CHANGE:
            if (data && data.checked === true && data.id === "pay-with-rewards-toggle") {
                /*your code*/
            }
            break;
    }
});

rewards_apply

Show details

Trigger: This event is triggered when a shopper has applied their rewards balance.Example

glegem("OnClientEvent", function (source, data) {
    switch (source) {
        case GEMerchantUtils.ClientEvents.BUTTON_CLICKED:
            if (data.id === "ApplyLoyaltyCreditGiftCard") {
                /*your code*/
            }
            break;
    }
});

rewards_amend_balance

Show details

Trigger: This event is triggered when a shopper changes the amount of rewards to apply.Example

glegem("OnClientEvent", function (source, data) {
    switch (source) {
        case GEMerchantUtils.ClientEvents.BUTTON_CLICKED:
            if (data && (data.id === "loyalty-minus-btn" || data.id === "loyalty-plus-btn")) {
                /*your code*/
            }
            break;
    }
});