- Documentation Portal
- SDK and API
- Global‑e Analytics and Marketing
- Advanced Checkout Events
Advanced Checkout Events
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.
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 |
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.
| 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
| 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_CHANGED
event 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:
| 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_COMPLETED
event withSameAsBilling
as the default, since billing and shipping are marked as the same by default. If the shopper chooses a different shipping address, theSHIPPING_ADDRESS_COMPLETED
event will fire again, this time withAlternative
as the value forShippingAddressType
.
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
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
| 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:
| 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_CLICKED
event tracks when a customer initiates a payment by clicking the Pay
button. 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.
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:
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_CHANGE
event 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_BLUR
event 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:
| 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_CLICKED
event tracks when a customer initiates a payment by clicking the Pay
button. 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..
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:
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_BLUR
event 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.