Update an outcome definition

PATCH

https://api.runledger.co/v1/outcome_definitions/:outcome_definition

PATCH

/v1/outcome_definitions/:outcome_definition

curl -X PATCH https://api.runledger.co/v1/outcome_definitions/chat_resolution \
     -H "Authorization: Bearer <api_key>" \
     -H "Content-Type: application/json" \
     -d '{}'

{
  "id": "od_7cV2bN5mXq",
  "object": "string",
  "key": "chat_resolution",
  "name": "Chat resolution",
  "event_name": "resolution.chat",
  "criteria": "string",
  "version": 3,
  "confirmation_window": "PT24H",
  "reversal_horizon": "P30D",
  "reversal_rules": [
    {
      "key": "reopened",
      "event_name": "conversation.reopened",
      "action": "reverse",
      "condition": {
        "property": "csat",
        "operator": "eq",
        "value": "2"
      },
      "applies_to": "any",
      "reason_code": "not_resolved"
    }
  ],
  "dispute_settings": {
    "decision_window": "P7D",
    "default_decision": "reverse"
  },
  "metadata": {},
  "livemode": true,
  "created_at": "2024-01-15T09:30:00Z",
  "version_created_at": "2024-01-15T09:30:00Z",
  "preset": "support_chat",
  "warnings": [
    {
      "code": "confirmation_window_short",
      "message": "The charge confirms almost at once, so only the reversal horizon protects you.",
      "path": "outcome_definitions.0.confirmation_window"
    }
  ],
  "actor": {
    "type": "user",
    "id": "usr_4tN8vB2cXk",
    "name": "Claude Code",
    "on_behalf_of": "usr_4tN8vB2cXk",
    "client": "claude-code"
  },
  "stats": {
    "charges": 4210,
    "confirmed": 3980,
    "reversed": 168,
    "disputed": 31,
    "reversal_rate": "0.0405",
    "dispute_rate": "0.0074"
  }
}

Changing the criteria, clocks, rules or dispute settings creates a new version that applies to outcome charges created from now on. Existing charges keep the terms of the version they were created under, and each charge records its version as evidence. Changing only name or metadata does not create a version. Each version records who made it.

Authentication

AuthorizationBearer

A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.

Path parameters

outcome_definitionstringRequired

The outcome definition ID (od_...) or key.

Request

This endpoint expects an object.

namestringOptional

criteriastringOptional<=2000 characters

presetstringOptional

Fills in the clocks and dispute settings you don't send in this request, as on create.

confirmation_windowstringOptional

reversal_horizonstringOptional

reversal_ruleslist of objectsOptional

Replaces the whole list.

dispute_settingsobjectOptional

metadatamap from strings to stringsOptional

Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.

Response

The outcome definition at its new version.

idstring

object"outcome_definition"

keystring

namestring

event_namestring

criteriastring

versioninteger

Starts at 1 and goes up by one with each change to terms.

confirmation_windowstring

reversal_horizonstring

reversal_ruleslist of objects

dispute_settingsobject

metadatamap from strings to strings

Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.

livemodeboolean

created_atdatetime

version_created_atdatetime

When this version took effect.

presetstringOptional

The preset used to fill in values when this version was made, if any. The values below are explicit either way.

warningslist of objectsOptional

Only on create and update responses. Values outside the recommended ranges, with the reason.

actorobjectOptional

Who made this version.

statsobjectOptional

The last 30 days, across all versions.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error