Skip to content
SarvexDocs
Esc
↑↓navigate↵open⌘Jpreview

A checkout session failed

RECEIVEserving.checkout.failed
Message
event_versionstringrequired

Semver of this event contract. Starts at "1.0"; bump on a breaking payload change.

event_idstringrequired
occurred_atstring<date-time>required
merchant_idstringrequired
store_idstringrequired
surfacestringrequired

Best-effort Google surface, derived from the UCP-Agent header's profile-URL host. "unknown" when the header is absent or doesn't recognizably match a known Google surface.

Allowed:google_ai_modegoogle_geminiunknown
checkout_idstring

Absent on serving.request.telemetry_recorded; the Sarvex checkout session id everywhere else.

checkout_session_idstringrequired
codestringrequired

Raw SessionError code from checkout_service.go, e.g. CONNECTOR_CREATE_FAILED, CONNECTOR_UPDATE_FAILED, FRESHNESS_GUARD_FAILED, ORDER_CREATION_FAILED. Classified into a checkoutcause.Cause downstream, not here. Identical to failure.code (below) — kept for the pre-existing session-projection consumer, which reads this flat field.

messagestring
stagestringrequired
Allowed:createupdatecomplete_freshness_guardcomplete
failurefailure_detailrequired

The versioned lifecycle contract's structured failure detail — a duplicate view of code/message/stage above using the contract's own closed enums, not new information.

Show properties
codefailure_coderequired

Closed enum — every checkout failure code the serving plane can currently produce.

Allowed:CONNECTOR_CREATE_FAILEDCONNECTOR_UPDATE_FAILEDFRESHNESS_GUARD_FAILEDORDER_CREATION_FAILED
stagefailure_stagerequired

Closed enum. Only session_create, cart_update, payment_submission, and confirmation are reachable by any failure_code this contract currently produces — negotiation and escalation are part of the full contract enum but not yet reachable (see checkout_failed).

Allowed:negotiationsession_createcart_updatepayment_submissionconfirmationescalation
handler_idstring | nullrequired

The selected payment instrument's handler_id, when a payment instrument had been selected at the time of failure; null otherwise.

detailstringrequired

No PII, no payment credential material of any kind — see the failed message's description.

cart_snapshotcart_snapshotrequired
Show properties
currencystringrequired
total_minorintegerrequired
line_itemscart_line_item_snapshot[]required
Show properties
Array of cart_line_item_snapshot
skustringrequired
quantityintegerrequired
unit_price_minorintegerrequired

0 when no live connector pricing was ever resolved for this session (see cart_snapshot).

Headers
message_idstringrequired

Unique per message; consumers de-duplicate on this.

ordering_keystringrequired

The store_id. Guarantees per-store ordering; the catalog/serving tenant boundary (a store belongs to one merchant — see architecture §2a).

occurred_atstring<date-time>required
sequenceinteger<int64>

Monotonic per-connector sequence carried from the origin signal (ingest events only).

trace_idstring

Correlates a chain of events from one originating cause.

schema_versionstringrequired
Try it
Server
Payload

Live sending isn't possible for pubsub from a browser tab — copy the sample above and run it against your broker.

Message
{
  "event_version": "1.0",
  "event_id": "string",
  "occurred_at": "2019-08-24T14:15:22Z",
  "merchant_id": "string",
  "store_id": "string",
  "surface": "google_ai_mode",
  "checkout_id": "string",
  "checkout_session_id": "string",
  "code": "string",
  "message": "string",
  "stage": "create",
  "failure": {
    "code": "CONNECTOR_CREATE_FAILED",
    "stage": "negotiation",
    "handler_id": "string",
    "detail": "string"
  },
  "cart_snapshot": {
    "currency": "USD",
    "total_minor": 0,
    "line_items": [
      {
        "sku": "string",
        "quantity": 0,
        "unit_price_minor": 0
      }
    ]
  }
}