Skip to navigation
API ReferenceOutcomesOutcome definitions

Create an outcome definition

Defines one kind of outcome you charge for: the event that reports it, the criteria you agreed with your customers, the two clocks, the reversal rules and the dispute settings. Plans set its price. The clocks have no silent default: send them, or send a preset from GET /v1/outcome_definition_presets and the server fills in the values you left out and stores them explicitly. Values outside the recommended ranges are accepted and come back as warnings.

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.

Request

This endpoint expects an object.
keystringRequiredformat: "^[a-z][a-z0-9_]{1,63}$"
Your stable identifier. Can't change.
namestringRequired
event_namestringRequired

The track() event that reports this outcome. Unique across outcome definitions.

criteriastringRequired<=2000 characters
What counts as this outcome, in the words you agreed with your customers. Stamped on every charge by version.
presetstringOptional

A preset key, such as support_chat, that fills in confirmation_window, reversal_horizon and dispute_settings where you don’t send them. The stored definition holds explicit values and echoes the preset’s key, so changing a preset later never changes it.

confirmation_windowstringOptional

How long a new charge stays pending before it confirms by default, as an ISO 8601 duration from PT0S to P30D. Required unless preset is sent. Recommended PT1H to P7D; outside that range the response carries a warning.

reversal_horizonstringOptional

How long after confirmation a charge can still be reversed, as an ISO 8601 duration from PT0S to P180D. After it passes, the charge locks, unless a dispute is still open. Required unless preset is sent. Recommended P7D to P90D; outside that range the response carries a warning.

reversal_ruleslist of objectsOptional
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 new outcome definition, at version 1.
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
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error