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

Get a checkout session, including its diagnosis

GET/checkout-sessions/{checkout_session_id}
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.

Path parameters
checkout_session_idstringrequired

A checkout session the caller's merchant owns. Authorized server-side against the principal; not a free-form tenant selector.

Responses
200

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>
404

Resource not found within the caller's tenant.

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
Try it
Server
Authorization
Parameters
Request
curl -X GET "https://api.sarvex.example.com/v1/checkout-sessions/string" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "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"
}