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

List lost-checkout entries

Default sort is lost_revenue_minor descending, occurred_at descending as tiebreak (R14) — this is a product invariant, not a convenience default; a client may request sort=occurred_at instead.

GET/ledger/entries
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
cursorstring

Opaque pagination cursor from the previous page's page.cursor.

limitinteger

Maximum items per page.

min 1 · max 100 · default: 25
causeledger_cause
Allowed:payment_handlerprofile_mismatchsync_freshnessescalation_dropoffplatform_errortimeoutbuyer_abandonedunclassified
statusledger_entry_status
Allowed:openacknowledgedresolved
store_idstring
surfacestring
fromstring<date-time>

Filters by occurred_at >= from.

tostring<date-time>

Filters by occurred_at <= to.

sortstring

Default lost_revenue_minor (R14). occurred_at is the one supported alternate.

default: "lost_revenue_minor"
Allowed:lost_revenue_minoroccurred_at
Responses
200

Lost-checkout entries.

dataledger_entry[]required
Show properties
Array of ledger_entry
entry_idstring
occurred_atstring<date-time>
checkout_idstring
store_idstring
surfacestring | null
Allowed:ucp_checkout
stagestring
failure_codestring

Raw serving-plane signal (e.g. CONNECTOR_CREATE_FAILED), or the literal ABANDONED for an abandonment entry.

causeledger_cause

Closed classification — see internal/planes/control/ledger.Cause.

Allowed:payment_handlerprofile_mismatchsync_freshnessescalation_dropoffplatform_errortimeoutbuyer_abandonedunclassified
recommended_actionstring

Merchant-readable and imperative — what to do, never protocol jargon.

lost_revenue_minorinteger

Amount in minor units (cents). Never an estimate — see revenue_unknown.

currencystring | null
revenue_unknownboolean

True when no cart snapshot was available at the point of failure — lost_revenue_minor is 0 in that case, never imputed.

statusledger_entry_status
Allowed:openacknowledgedresolved
status_changed_atstring<date-time>
created_atstring<date-time>
pagepagerequired
Show properties
cursorstring | nullrequired
has_morebooleanrequired
403

Authenticated but not permitted (e.g. non-operator on an operator route).

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
422

Request body failed validation.

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
Try it
Server
Authorization
Parameters
Request
curl -X GET "https://api.sarvex.example.com/v1/ledger/entries" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "data": [
    {
      "entry_id": "led_01J...",
      "occurred_at": "2019-08-24T14:15:22Z",
      "checkout_id": "string",
      "store_id": "string",
      "surface": "ucp_checkout",
      "stage": "string",
      "failure_code": "string",
      "cause": "payment_handler",
      "recommended_action": "string",
      "lost_revenue_minor": 0,
      "currency": "USD",
      "revenue_unknown": true,
      "status": "open",
      "status_changed_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "page": {
    "cursor": "string",
    "has_more": true
  }
}