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

List sessions currently in progress

Non-terminal sessions with last_activity_at inside the active window (default 30 minutes). Polling, not streaming (no websockets/SSE) — the console is expected to poll this endpoint on an interval (~15-30s). Capped result set; page.has_more is true if the cap truncated the result rather than there being a next page to fetch.

GET/checkout-sessions/live
Authorization
AuthorizationBearer token (JWT) · headerrequired

JWT issued by the external IdP via the OAuth 2.0 authorization-code flow (Kinde in production; a simulator in test). The client obtains it and sends it as a Bearer token on every authenticated call. Sarvex's services verify it — issuer, audience, signature (IdP JWKS), expiry — and read identity and tenant from its claims. Sarvex does not issue or revoke these tokens. merchant_id/store_id are read from the verified claims (and the merchant→store mapping), never from the URL. The operator scope is required for /operator/*. Operators acting on a specific merchant pass the X-Operate-As header, which is recorded in the audit log.

Query parameters
window_minutesinteger
default: 30
limitinteger
min 1 · max 200 · default: 200
Responses
200

Live checkout sessions.

datacheckout_session[]required
Show properties
Array of checkout_session
checkout_idstring
store_idstring
surfacestring

The checkout surface. There is exactly one — UCP checkout.

Allowed:ucp_checkout
agent_platformstring | null

Best-effort agent platform identification; absent when unavailable.

statecheckout_session_state
Allowed:initiatedcart_activeescalatedawaiting_paymentcompletedfailedabandoned
current_stagestring
started_atstring<date-time>
last_activity_atstring<date-time>
terminal_atstring<date-time> | null
cart_summarycart_summary
Show properties
currencystring
total_minorinteger

Amount in minor units (cents).

item_countinteger
escalationobject | null
Show properties
reasonstring
escalated_atstring<date-time>
continue_url_issuedboolean
returned_atstring<date-time> | null

Set once any further session activity is observed after the escalation — the checkout flow has no explicit "buyer clicked continue_url" signal, so any subsequent event is the proxy.

resolvedboolean

True once the session reaches a terminal state after having been escalated at least once.

failureobject | null
Show properties
codestring

Raw failure code (e.g. CONNECTOR_CREATE_FAILED, FRESHNESS_GUARD_FAILED, ORDER_CREATION_FAILED).

causestring

Classified cause — see checkout_diagnosis.cause.

stagestring
diagnosisobject | null
Show properties
stage_reachedstring
causestring

Closed classification — see internal/pkg/checkoutcause.Cause.

Allowed:connector_create_failedconnector_update_failedpricing_staleorder_creation_failedescalation_stalledbuyer_abandonedunknown
plain_language_summarystring
recommended_actionstring
evidenceinteger[]

The specific timeline seq values supporting this conclusion.

event_countinteger
updated_atstring<date-time>
pagepagerequired
Show properties
cursorstring | nullrequired
has_morebooleanrequired
Try it
Server
Authorization
Parameters
Request
curl -X GET "https://api.sarvex.example.com/v1/checkout-sessions/live" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "data": [
    {
      "checkout_id": "string",
      "store_id": "string",
      "surface": "ucp_checkout",
      "agent_platform": "string",
      "state": "initiated",
      "current_stage": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "last_activity_at": "2019-08-24T14:15:22Z",
      "terminal_at": "2019-08-24T14:15:22Z",
      "cart_summary": {
        "currency": "AUD",
        "total_minor": 0,
        "item_count": 0
      },
      "escalation": {
        "reason": "string",
        "escalated_at": "2019-08-24T14:15:22Z",
        "continue_url_issued": true,
        "returned_at": "2019-08-24T14:15:22Z",
        "resolved": true
      },
      "failure": {
        "code": "string",
        "cause": "string",
        "stage": "string"
      },
      "diagnosis": {
        "stage_reached": "string",
        "cause": "connector_create_failed",
        "plain_language_summary": "string",
        "recommended_action": "string",
        "evidence": [
          0
        ]
      },
      "event_count": 0,
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "page": {
    "cursor": "string",
    "has_more": true
  }
}