Change an entry's triage status

Status transitions only, forward-only (open -> acknowledged -> resolved). A reversal, or any other field, is rejected.

PATCH/ledger/entries/{entry_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

entry_idstringrequired

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

Request body

requiredapplication/json

statusledger_entry_statusrequired

Allowed:openacknowledgedresolved

Responses

200

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

403

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

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

detailsobject | null

404

Resource not found within the caller's tenant.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

detailsobject | null

409

The requested status is not forward of the entry's current status.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

detailsobject | null

422

Request body failed validation.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

detailsobject | null

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (JWT)Remember on this deviceInclude my values in samples

Parameters

entry_idpath*A ledger entry the caller's merchant owns. Authorized server-side against the principal; not a free-form tenant selector.

Bodyapplication/json

statusstring*

Request

curl -X PATCH "https://api.sarvex.example.com/v1/ledger/entries/string" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "open"
}'

const response = await fetch("https://api.sarvex.example.com/v1/ledger/entries/string", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"status\": \"open\"\n}"
});

import requests

response = requests.patch(
    "https://api.sarvex.example.com/v1/ledger/entries/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"status\": \"open\"\n}",
)

Response

{
  "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"
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}