Checkout Error
Also known as: Checkout Failure, Payment Error, Checkout Validation Error, checkout_error
Fires when a checkout step shows the shopper an error: payment decline, form validation, stock, shipping or promo failure. Each hit carries error type, code and step to locate funnel friction.
Event Serialization
always
Business Use Case
1️⃣ Checkout Product Manager: payment-step error share rises week on week → prioritises a fix for the top error_code. 2️⃣ Payments team: decline errors spike for one payment_provider → reroutes traffic or escalates to the gateway. 3️⃣ Merchandising: inventory errors at checkout climb → tightens stock sync and oversell buffers for affected SKUs. 4️⃣ Customer Service: promo or address errors surge after a release → updates help macros and alerts Engineering.
Business Criticality
High
Journey / Navigation Area
Checkout
Owning Function
Product
Calculation Notes
1️⃣ Fire once per error rendered to the shopper, at display time or on the server response; never on silent retries. 2️⃣ Dedupe on cart_id + checkout_step + error_code within 5 s; a failed re-submit is a new hit with payment_attempt_number + 1. 3️⃣ Required: error_type, error_code, checkout_step, checkout_type, cart_id. Optional: error_source, error_message, value, currency, traffic_type. 4️⃣ Optional on payment-step errors: payment_type, payment_provider, payment_attempt_number (1 on first attempt, +1 per re-submit). 5️⃣ error_type is a fixed enum (payment_declined, validation, inventory, shipping, promo, system); map raw gateway codes server-side. 6️⃣ No PII: no card numbers, emails or addresses; error_message is a templated key, never raw text echoing user input. 7️⃣ Analytics consent only; exclude internal/test via traffic_type. Avoid: pre-submit field hints, numeric error_code, missed server declines.
Platform Events
| Platform | Event |
|---|---|
| Google Analytics 4 | checkout_error |
| Adobe | checkoutError |
Data Mappings
W3 Data Layer
{
"event": [
{
"eventInfo": {
"eventName": "checkout_error",
"eventAction": "checkout_error"
},
"attributes": {
"error_type": "payment_declined",
"error_code": "string",
"error_source": "client",
"error_message": "string",
"checkout_step": "payment",
"checkout_type": "guest",
"cart_id": "string",
"payment_type": "string",
"payment_provider": "string",
"payment_attempt_number": 1,
"value": 0,
"currency": "USD",
"traffic_type": "string"
}
}
]
}GA4 Data Layer
{
"event": "checkout_error",
"error_type": "payment_declined",
"error_code": "string",
"error_source": "client",
"error_message": "string",
"checkout_step": "payment",
"checkout_type": "guest",
"cart_id": "string",
"payment_type": "string",
"payment_provider": "string",
"payment_attempt_number": 1,
"value": 0,
"currency": "USD",
"traffic_type": "string"
}Adobe Client Data Layer
{
"event": "checkoutError",
"checkoutError": {
"error_type": "payment_declined",
"error_code": "string",
"error_source": "client",
"error_message": "string",
"checkout_step": "payment",
"checkout_type": "guest",
"cart_id": "string",
"payment_type": "string",
"payment_provider": "string",
"payment_attempt_number": 1,
"value": 0,
"currency": "USD",
"traffic_type": "string"
}
}XDM Mapping
{
"eventType": "commerce.checkoutError",
"_tenant": {
"checkoutError": {
"errorType": "payment_declined",
"errorCode": "string",
"errorSource": "client",
"errorMessage": "string",
"checkoutStep": "payment",
"checkoutType": "guest",
"cartId": "string",
"paymentType": "string",
"paymentProvider": "string",
"paymentAttemptNumber": 1,
"value": 0,
"currency": "USD",
"trafficType": "string"
}
}
}Source Data
Digital Analytics (GA4)
Dependencies
Prerequisite: List the dependencies required for this Event
Dimensions:
Report Attributes
Checkout Error Type Error Code Checkout Step Payment Method Payment Provider Checkout Type Device Category
Segment Eligibility
true
Governance
Dimensions
Related Dimensions
Derived Dimensions
Derived Entities
Derived KPIs
Governance & Metadata
GitHub
catalog/events/checkout-error.yml