Resolve a dispute

POST

https://api.runledger.co/v1/disputes/:dispute_id/resolve

POST

/v1/disputes/:dispute_id/resolve

curl -X POST https://api.runledger.co/v1/disputes/dispute_id/resolve \
     -H "Authorization: Bearer <api_key>" \
     -H "Content-Type: application/json" \
     -d '{
  "decision": "uphold"
}'

{
  "id": "dsp_3sE6rT9yUi",
  "object": "string",
  "outcome_charge": "string",
  "customer": "string",
  "status": "open",
  "reason_code": "not_resolved",
  "opened_by": "end_customer",
  "decider": "merchant",
  "decide_by": "2024-01-15T09:30:00Z",
  "default_decision": "reverse",
  "metadata": {},
  "livemode": true,
  "created_at": "2024-01-15T09:30:00Z",
  "rule": "string",
  "trigger_event": "string",
  "description": "string",
  "evidence": {
    "description": "Customer confirmed the refund arrived and closed the chat.",
    "url": "https://app.example.com/conversations/conv_4821",
    "properties": {}
  },
  "decision": "uphold",
  "decided_by": "merchant",
  "actor": {
    "type": "user",
    "id": "usr_4tN8vB2cXk",
    "name": "Claude Code",
    "on_behalf_of": "usr_4tN8vB2cXk",
    "client": "claude-code"
  },
  "decision_note": "string",
  "decided_at": "2024-01-15T09:30:00Z",
  "reversal": "string"
}

Records your decision on an open dispute. uphold keeps the charge, and a pending charge confirms at once. A confirmed charge goes back to confirmed, or locks at once if its horizon passed while the dispute was open. reverse reverses the charge and creates a reversal, even when the horizon has passed.

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

dispute_idstringRequired

The dispute ID (dsp_...).

Request

This endpoint expects an object.

decisionenumRequired

Allowed values:

notestringOptional<=2000 characters

The reason for the decision. Kept on the dispute.

Response

The resolved dispute.

idstring

object"dispute"

outcome_chargestring

customerstring

statusenum

open until decided. upheld: the charge stands. reversed: the charge was reversed.

Allowed values:

reason_codeenum

Why a charge was reversed. New codes may be added.

opened_byenum

Allowed values:

deciderenum

Who decides. Always merchant (you).

Allowed values:

decide_bydatetime

The deadline. dispute.decision_due fires 24 hours before it.

default_decisionenum

Allowed values:

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

rulestringOptional

The rule key, when a rule opened it.

trigger_eventstringOptional

descriptionstringOptional

evidenceobjectOptional

What shows an outcome happened, stamped on the outcome charge. Keep it short and factual; it is shown to people deciding disputes. Free text is sanitized before it reaches dashboards or agent tools.

decisionenumOptional

Allowed values:

decided_byenumOptional

merchant if you decided, default if the deadline passed.

Allowed values:

actorobjectOptional

Who recorded the decision. Left out while open and when decided_by is default.

decision_notestringOptional

decided_atdatetimeOptional

reversalstringOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error