Skip to main content
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. 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. 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.ExamplesPOST {globale domain}/Return/GetReturnDocuments
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
}
});
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.”);
}
}
});
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 Practices The 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. 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.
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);
}
}
});
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 Practices The 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. 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 Practices There 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.
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. 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 Practices The 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 actionvalue 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. 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 Practices The 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. 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});
}
});
Implementation Tips and Best Practices The 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 actionvalue 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.. 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 Practices This 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.