Skip to main content
POST
Create a rule
Creates a rule within a program and rule set. A rule consists of a CEL condition that is evaluated against each incoming event and an actions array that executes when the condition matches. Use description to add a human-readable summary of what the rule does. Common actions include crediting balances, incrementing counters, and setting tags. Pass rule_set_id to choose a containing set. Omit it to use the program’s default set. To place the rule, use position with first, last, before, or after. Relative placement requires the stable sibling ID in reference_id. If you omit position, Scrip appends the rule. Scrip numbers rule positions 1..N with no gaps within each set. ACTIVE and SUSPENDED rules both occupy unique positions. Set stop_after_match to true to prevent later rules in the same set from firing after this rule matches and its actions execute successfully. Other rule sets continue. A skipped execution, such as BUDGET_EXCEEDED, does not trigger the stop. active_from and active_to define an optional time window using RFC 3339 timestamps. The window is checked against the event’s event_timestamp (the same value CEL sees as now), not the wall-clock time at processing. active_from is inclusive, active_to is exclusive. A matching rule outside the window records an OUTSIDE_TIME_WINDOW skipped evaluation. Event timestamps are caller-supplied, so historical imports with an event_timestamp inside a past window do fire time-windowed rules. Use these to layer promotional rules on top of permanent base rules. budgets limit how much of an asset the rule can credit. Use PROGRAM for a shared limit or PARTICIPANT for a limit per recipient. You can set one of each for the same asset. A credit that would exceed either limit skips the whole rule. See Budgets for schedules, validation errors, skip reasons, and resets. A rule is created in ACTIVE status by default. You can also set it to SUSPENDED at creation. Rules cannot be created under an archived program. The response includes the resulting rule_configuration_version.
For assignment and ordering patterns, see the Rule sets guide.

Authorizations

​
X-API-Key
string
header
required

API key passed in the X-API-Key header.

Body

application/json

Rule with CEL condition and actions array

Request body for creating a new rule with CEL condition and actions

​
actions
CREDIT action · object · DEBIT action · object · HOLD action · object · RELEASE action · object · RELEASE action · object · FORFEIT action · object · VOID_HOLD action · object · TAG action · object · UNTAG action · object · COUNTER action · object · SET_ATTRIBUTE action · object · SET_TIER action · object · SCHEDULE_EVENT action · object · BROADCAST action · object[]
required

Actions to execute when the condition matches (must be non-empty). Each action has a type field that determines which other fields are relevant.

Minimum array length: 1

Credit an asset to the target. Requires asset_id and a positive amount. reference_id, expires_at, and matures_at require a LOT-mode asset and are rejected on a SIMPLE-mode asset.

Example:
​
condition
string
required

CEL expression that determines when the rule fires

Minimum string length: 1
Example:

"event.type == 'purchase'"

​
name
string
required

Display name for the rule

Required string length: 1 - 255
Example:

"Purchase Reward"

​
program_id
string<uuid>
required

Program to attach this rule to

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
active_from
string<date-time>

Start of the rule's active window (RFC 3339). Null means immediately active. Checked against the event's event_timestamp, inclusive.

Example:

"2024-01-01T00:00:00Z"

​
active_to
string<date-time>

End of the rule's active window (RFC 3339). Null means no end date. Checked against the event's event_timestamp, exclusive.

Example:

"2024-12-31T23:59:59Z"

​
budgets
(Lifetime budget · object | Cron budget · object | Interval budget · object)[]

Optional budget constraints for this rule. Omit or pass null for no budgets.

Never resets. schedule_type, cron_expression, and interval are all rejected.

​
description
string

Human-readable summary of what this rule does

Maximum string length: 1000
Example:

"Awards 10 points per dollar spent"

​
position
object

Semantic insertion. Omit both order and position to append.

​
rule_set_id
string<uuid>

Rule set to attach this rule to. Omit to use the program's default set.

Example:

"550e8400-e29b-41d4-a716-446655440001"

​
status
enum<string>

Initial lifecycle status (ACTIVE or SUSPENDED). Defaults to ACTIVE.

Available options:
ACTIVE,
SUSPENDED
Example:

"ACTIVE"

​
stop_after_match
boolean

When true, no subsequent rules in this set evaluate after this one matches; other sets continue

Example:

false

Response

Rule created

​
actions
object[]

Actions to execute when the condition matches

Example:
​
active_from
string<date-time>

Start of the rule's active window (RFC 3339, null if always active). Checked against the event's event_timestamp, inclusive.

Example:

"2024-01-01T00:00:00Z"

​
active_to
string<date-time>

End of the rule's active window (RFC 3339, null if no end date). Checked against the event's event_timestamp, exclusive.

Example:

"2024-12-31T23:59:59Z"

​
budgets
object[]

Budget constraints applied to this rule

​
condition
string

CEL expression that determines when the rule fires

Example:

"event.type == 'purchase' && event.amount > 0"

​
created_at
string<date-time>

When this rule was created (RFC 3339)

Example:

"2024-01-15T10:30:00Z"

​
deleted_at
string<date-time>

When this rule was archived (null if not archived)

Example:

"2024-06-01T00:00:00Z"

​
description
string

Human-readable summary of what this rule does

Example:

"Awards 10 points per dollar spent"

​
id
string<uuid>

Unique identifier for this rule

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
name
string

Display name

Example:

"Purchase Reward"

​
order
integer

Evaluation position within the containing rule set (lower = first; ACTIVE and SUSPENDED rules occupy unique positions)

Example:

1

​
program_id
string<uuid>

Program this rule belongs to

Example:

"550e8400-e29b-41d4-a716-446655440001"

​
rule_configuration_version
integer

Resulting program rule-configuration revision. Present on mutation responses.

Example:

4

​
rule_set_id
string<uuid>

Rule set that contains this rule and scopes its order and stop_after_match behavior

Example:

"550e8400-e29b-41d4-a716-446655440002"

​
status
string

Lifecycle status: ACTIVE, SUSPENDED, or ARCHIVED

Example:

"ACTIVE"

​
stop_after_match
boolean

When true, no subsequent rules in this set evaluate after this one matches; other sets continue

Example:

false

​
updated_at
string<date-time>

When this rule was last modified (RFC 3339)

Example:

"2024-01-15T10:30:00Z"

​
warnings
object[]

Non-blocking advisories about the rule's condition or action expressions, such as unknown state-key typos or deprecated CEL aliases. Present on create/update only; never blocks the save.