Common Payload Fields
Everymx-analytics event payload contains the following base fields. Event-specific additional fields are documented under each event in the Event Reference.
List of fields
event
: string The event name (for example, "initiate", "payment_initiated").
paymentMode
: string Payment mode. Currently it is always "online".
lineItems
: LineItem[] Cart items at the time the event fired. See LineItem Schema.
totalAmount
: number Original cart total in paise (before shipping or discounts).
latestTotal
: number Current order total in paise, reflecting any applied discounts and shipping.
shippingAmount optional
: number Shipping cost in paise. Undefined if not yet calculated.
couponDiscountValue
: number Discount applied by an active coupon in paise. 0 if no coupon is active.
isScriptCouponApplied
: boolean Whether an automatic/script-based discount is applied.
currency
: string Transaction currency code (for example, "INR").
phone
: string Customer’s phone number. Empty string if not yet available.
email
: string Customer’s email address. Empty string if not yet available.
first_name
: string Customer’s first name. Empty string if not yet available.
last_name
: string Customer’s last name. Empty string if not yet available.
state
: string Customer’s state. Empty string if address not yet selected.
city
: string Customer’s city. Empty string if address not yet selected.
Important Payload Information
-
Field Naming Conventions: Payloads use mixed casing based on their source. Amount and mode fields (for example,
latestTotal,paymentMode) use camelCase as they originate from JavaScript. Customer identity and address fields (for example,first_name,state_code) use snake_case as they originate from backend API responses. - Currency Format: All amounts are represented in paise (integers). To get the value in Rupees, divide by 100 (for example, 49900 = ₹499.00).
-
Progressive Data Population: Customer fields are populated in stages.
phoneandemailappear after contact entry. However,first_name,last_name,stateandcityremain empty strings until theaddress_info_submittedevent fires. -
After
address_info_submittedfires, additional fields —state_code,country_name,zipcode,line1andline2— become available in all subsequent payloads. -
The
country_namefield actually contains a 2-letter country code (for example, “in”) rather than the full name of the country.
LineItem Schema
Each object in thelineItems array reflects what was passed in line_items when creating the order. All fields are optional as not every integration populates every field.
List of Fields
name optional
: string Product name.
description optional
: string Product description. May be an empty string.
image_url optional
: string | null Product image URL.
price optional
: number Original price in paise.
offer_price optional
: number Effective/offer price in paise.
quantity optional
: number Quantity in cart.
tax_amount optional
: number Tax amount in paise.
variant_id optional
: string Product variant identifier.
sku optional
: string Product SKU.
title optional
: string Alternate product name (used by some integrations).
id optional
: string | number Generic product/item identifier.
product_id optional
: string | number Product identifier.
discount optional
: number Discount amount in paise.
product_url optional
: string Relative URL to the product page.
brand optional
: string Product brand.
vendor optional
: string Product vendor.
Address Schema
Theaddress object is present in address_selected and address_added events.
Fields for address_selected (saved address)
id
: string Unique address identifier.
entity_id
: string Internal Razorpay identifier.
entity_type
: string Internal Razorpay identifier.
type
: string Address type, for example, "shipping_address".
primary
: boolean Indicates whether this is the customer’s primary address.
name
: string Full name on the address.
line1
: string Address line 1.
line2
: string Address line 2. May be empty.
zipcode
: string Postal or ZIP code.
city
: string City.
state
: string State name.
country
: string 2-letter country code, for example, "in" for India.
contact
: string Phone number associated with this address.
tag
: string Address label, for example, "Home" or "Work".
landmark
: string Landmark. Empty string if not provided.
Fields for address_added (new address from form)
Server-assigned fields (id, entity_id, entity_type, primary, type) are absent because the address is not yet saved. Two additional form-specific fields are present:
name
: string Full name on the address.
line1
: string Address line 1.
line2
: string Address line 2. May be empty.
zipcode
: string Postal or ZIP code.
city
: string City.
state
: string State name.
country
: string 2-letter country code, for example, "in" for India.
contact
: string Phone number associated with this address.
tag
: string Address label, for example, "Home" or "Work".
landmark
: string Landmark. Empty string if not provided.
save_my_address
: boolean Indicates whether the customer opted to save this address.
new_shipping_address_cta
: any Internal form field.
Event Reference
Events are listed in the order they typically occur during a customer journey.initiate
When it fires: The Magic Checkout modal opens. Additional fields: None beyond common fields.Example Payload
contact_input_entered
When it fires: The customer enters their phone number or email address in the contact input field. Additional fields: None beyond common fields. Thephone or email fields in the common payload reflect what the customer entered.
otp_initiated
When it fires: An OTP is sent to the customer’s phone number. Additional fields:otp_verified
: boolean Always false. The OTP is sent but not yet verified.
Example Payload
otp_submitted
When it fires: The customer submits an OTP and it is accepted. This event does not fire on a failed OTP attempt. Additional fields:otp_verified
: boolean Always true. This event fires only on successful verification.
Example Payload
otp_skipped
When it fires: The customer skips the OTP verification step when the skip option is available. Additional fields: None beyond common fields.user_data
When it fires: The customer’s identity is confirmed and their profile data is available. This is the earliest event wherephone, email, first_name and last_name are reliably populated.
This event fires multiple times in a session: at login completion, when the customer proceeds from the address step and when payment is initiated. Each emission reflects the most current customer data.
Additional fields: None beyond common fields.
Example Payload
address_selected
When it fires: The customer selects a saved address from their address book and serviceability for that address is confirmed. This event fires only when the selected address changes. Selecting the same address again does not re-fire the event. Additional fields:address
: Address The selected address. See Address Schema.
address_added
When it fires: The customer submits a new address through the address form. Additional fields:address
: Address The newly added address. See Address Schema.
pincode_entered
When it fires: The customer enters a pincode in the address form. This event fires on blur of the pincode field. Additional fields:pinCode
: string The pincode value entered by the customer.
address_info_submitted
When it fires: Address information is finalised. This event fires in three scenarios:1
Step 1
The customer submits a new address form.
2
Step 2
The customer confirms an existing saved address.
3
Step 3
On checkout open, if the customer is already logged in and has a saved address on file.
state_code, country_name, zipcode, line1 and line2 at the top level, in addition to state and city.
Additional fields: None beyond common fields.
shipping_selected
When it fires: The customer confirms their address and the checkout proceeds to the payment screen. Additional fields:name optional
: string Shipping method name.
shipping_fee optional
: number Shipping cost in paise.
cod optional
: boolean Indicates whether COD is available for this shipping method.
cod_fee optional
: number COD fee in paise.
id optional
: string Shipping method identifier.
These fields (name, shipping_fee, cod, cod_fee, id) are present only in the standard checkout flow. In a quick-buy flow where payment occurs without an address step, this event fires without these fields.
Example Payload - Standard Flow
payment_page_reached
When it fires: The customer arrives at the payment method selection screen. Additional fields: None beyond common fields.coupon_applied
When it fires: The customer applies a coupon code and it is accepted. Additional fields:appliedCouponCode
: string The coupon code that was successfully applied.
amountBeforeDisc
: number Cart total before the discount, in paise.
amountAfterDisc
: number Cart total after the discount, in paise. Same as latestTotal.
The couponDiscountValue field in the common payload also reflects the discount amount in paise.
Example Payload
coupon_failed
When it fires: The customer attempts to apply a coupon code and it is rejected. Additional fields:couponCode
: string The coupon code the customer attempted to use.
errorMsg
: string The reason the coupon was rejected.
Example Payload
payment_initiated
When it fires: The customer selects a payment method and taps pay, initiating a payment attempt. Additional fields:paymentMethod
: string The payment method selected. Possible values: "upi", "card", "netbanking", "wallet", "emi", "cod".
Example Payload
payment_failed
When it fires: A payment attempt fails due to reasons such as bank decline, UPI timeout, or insufficient funds. Additional fields:failureReason
: string Description of why the payment failed.
Example Payload
checkout_abandoned
When it fires: The customer closes the Magic Checkout modal without completing payment. Additional fields:time_since_open
: number Milliseconds elapsed between checkout open and the moment of abandonment.
Event Behavior Notes
When do mx-analytics events fire?
These events only fire for Magic Checkout. If Magic Checkout features are not enabled on your account,mx-analytics events will not be emitted.
When are customer fields populated?
Customer fields start as empty strings and are populated progressively as the customer advances through the flow.user_data is the earliest event where all identity fields are reliably complete.
How often does user_data fire?
user_data fires multiple times per session: at login confirmation, after address is confirmed and when payment is initiated.
Can payment events fire multiple times?
payment_initiated and payment_failed can fire multiple times in one session if the customer retries after a failure.
Is there an event for failed OTP attempts?
otp_submitted only fires on a successful OTP. There is no event for a failed OTP attempt.
Does address_selected fire on every selection?
address_selected will not fire if the same address is selected twice. It only fires when the selection changes.
When does address_info_submitted fire?
address_info_submitted fires in three scenarios: new address submitted, existing address confirmed and automatically on checkout open for an already-logged-in customer with a saved address.
Are shipping_selected fields always present?
shipping_selected fields (name, shipping_fee, cod, cod_fee, id) are absent in the quick-buy flow where the customer pays without going through an address step.
When does checkout_abandoned fire?
checkout_abandoned fires only when checkout closes without a successful payment. If payment succeeds, the handler callback fires instead.