Rule Sets

Every rule belongs to one rule set. A rule set is a program-owned resource that gives related rules a shared execution priority and a local ordering scope. Rule sets organize execution. They do not enable or disable their rules. Every applicable ACTIVE rule across every rule set participates when Scrip processes an event. This example has three rule sets:

tracking has two rules: Track monthly spend, then Mark threshold crossing.
earning has two rules: Dining cashback, then Base cashback.
maintenance has one rule: Monthly reset.

Scrip runs those sets in that order, and the rules in each set in order. Dining cashback has stop_after_match: true, so a match skips Base cashback. Monthly reset still runs because it belongs to maintenance.

The default rule set

Each program has an automatically created rule set with key default. The default set starts at position 1. Creating another set appends it unless you request a different semantic position. You can omit rule_set_id when you create a rule. Scrip assigns the new rule to the program’s default set. Omitting the field when you update a rule preserves its current assignment. This keeps single-set integrations compatible while you adopt explicit sets.

The default set behaves like any other rule set during execution. Its key does not make it run first. Its order determines its position.

Create and inspect rule sets

Create a rule set under its program:

curl -X POST https://api.scrip.dev/v1/programs/$PROGRAM_ID/rule-sets \
  -H "Authorization: Bearer $SCRIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "earning",
    "name": "Earning rules",
    "position": {"placement": "last"}
  }'

The key is a stable program-scoped identifier. It must start with a lowercase letter and contain only lowercase letters, numbers, hyphens, or underscores. A rule set’s name and position can change, but its key cannot. List a program’s sets in execution order:

curl https://api.scrip.dev/v1/programs/$PROGRAM_ID/rule-sets \
  -H "Authorization: Bearer $SCRIP_API_KEY"

Get or update a set by ID:

curl https://api.scrip.dev/v1/programs/$PROGRAM_ID/rule-sets/$RULE_SET_ID \
  -H "Authorization: Bearer $SCRIP_API_KEY"

curl -X PATCH https://api.scrip.dev/v1/programs/$PROGRAM_ID/rule-sets/$RULE_SET_ID \
  -H "Authorization: Bearer $SCRIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Core earning rules"}'

Rule sets do not have delete or archive operations. Keep keys stable and use names to describe their current purpose. See the Rule sets API reference for all fields and error responses.

Assign and move rules

Pass rule_set_id when you create a rule:

{
  "program_id": "PROGRAM_ID",
  "rule_set_id": "EARNING_RULE_SET_ID",
  "name": "Dining cashback",
  "position": {"placement": "last"},
  "condition": "event.type == 'purchase' && event.mcc == '5812'",
  "actions": [
    {
      "type": "CREDIT",
      "asset_id": "CASHBACK_ASSET_ID",
      "amount": "${{ round(event.amount * 0.05, 2) }}"
    }
  ]
}

If you omit position, Scrip appends the rule to the selected set. If you omit rule_set_id, Scrip selects default before assigning the position. Move an existing rule with the version-guarded move endpoint:

curl -X POST https://api.scrip.dev/v1/rules/$RULE_ID/move \
  -H "Authorization: Bearer $SCRIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_set_id": "EARNING_RULE_SET_ID",
    "position": {"placement": "last"},
    "expected_rule_configuration_version": 7
  }'

Read expected_rule_configuration_version from the program’s complete configuration. The move compacts the source set and inserts the rule into the destination in one transaction. A stale version returns 409 rule_configuration_version_conflict without changing either set.

Execution order

Scrip builds one fixed sequence for each event:

Rule sets sort by rule_set.order, lowest first.
ACTIVE rules within each set sort by rule.order, lowest first.
Matching rule actions persist sequentially in that set and rule order.

All currently applicable ACTIVE rules across all sets participate. A lower set position changes when a set runs, not whether another set runs. Scrip numbers both order fields 1..N with no gaps. ACTIVE and SUSPENDED rules occupy unique positions within their containing set. Archived rules leave the sequence. For example:

Set	Set order	Rule	Rule order
Tracking	1	Track monthly spend	1
Tracking	1	Mark threshold crossing	2
Earning	2	Dining cashback	1
Earning	2	Base cashback	2

The two tracking rules run before the two earning rules. Dining cashback can use stop_after_match to skip Base cashback, but it cannot skip a tracking rule or a rule in any other set.

Conflict-safe reordering

Use semantic move endpoints when repositioning one set or rule. Use the atomic reorder endpoints when you have the complete desired list. Both paths require the current expected_rule_configuration_version, so a concurrent edit cannot silently overwrite your plan. Scrip shifts neighboring resources and returns the renumbered sequence. You do not need temporary positions or numeric gaps. See Managing rule configuration for consistent reads, full-list reorders, and atomic multi-resource changes.

Set-local stopping

When a matching rule has stop_after_match: true and its actions execute successfully, Scrip skips only the remaining rules in that same set. Processing continues with the next set. This makes one set a useful boundary for mutually exclusive rules. Put dining, grocery, and base earn-rate rules in one earning set. A dining match can stop the other earning rules while tracking, maintenance, or notification rules in other sets still participate. stop_after_match does not stop earlier rules. It also does not stop actions that already persisted. A skipped execution does not trigger the stop. For example, when a rule exceeds its budget, its actions roll back and processing continues with the next rule in the same set. Two mutually exclusive earn rates in one set:

{
  "name": "VIP Double Points",
  "rule_set_id": "earning-rules-uuid",
  "position": {"placement": "first"},
  "stop_after_match": true,
  "condition": "event.type == 'purchase' && 'vip' in participant.tags",
  "actions": [
    {"type": "CREDIT", "asset_id": "...", "amount": "${{ event.amount * 10 }}"}
  ]
}

{
  "name": "Standard Points",
  "rule_set_id": "earning-rules-uuid",
  "position": {"placement": "last"},
  "condition": "event.type == 'purchase'",
  "actions": [
    {"type": "CREDIT", "asset_id": "...", "amount": "${{ event.amount * 2 }}"}
  ]
}

VIPs get 10x because the first rule matches and stops the rest of the set. Everyone else gets 2x because the first rule does not match. Applicable rules in other sets still run for both participants.

One event-start snapshot

Scrip snapshots participant, program, and group state once at the start of each event, and every condition and dynamic expression in every set reads that same snapshot. A counter incremented by an earlier set is not visible to a later set during the same event. See State Snapshot Evaluation Behavior for the full behavior and the threshold-crossing pattern.

Event traces

Event details and impact responses include the execution-time rule_set_id on each recorded rule evaluation. Evaluations are returned in the historical set and rule order used for that event. This trace is not a census of all applicable rules. Clean false conditions have no row. Later rules in the current set that are not reached after a successful stop_after_match also have no row, while processing continues with the next set. See Get an event for skipped-evaluation filtering. Use the trace to identify the set that contained a rule when it ran. Moving a rule later does not change the recorded set identity for an existing evaluation.

Simulation boundaries

Single-rule simulation validates one rule’s condition and resolved actions. It does not run the program’s other rule sets. A successful single-rule simulation does not prove cross-set ordering, set-local stop_after_match behavior, or interactions among matching rules. Send representative events to a dedicated development program when you need the full execution path. See Testing multiple rule sets.

Recommended structure

Use a small number of sets with distinct responsibilities:

Key	Example order	Purpose
`default`	1	Compatibility for rules that omit `rule_set_id`
`tracking`	2	Counters, tags, and other state writes
`earning`	3	Mutually exclusive or cumulative reward rules
`maintenance`	4	Reset and lifecycle event handling

The Cashback card example shows three named sets executing after an intentionally empty default set while the earn-rate rules remain mutually exclusive.

Getting Started

Foundations

Earning

Participant State

Ledger & Balances

Spending

Operations

Advanced

Reference

The default rule set

Create and inspect rule sets

Assign and move rules

Execution order

Conflict-safe reordering

Set-local stopping

One event-start snapshot

Event traces

Simulation boundaries

Recommended structure

​The default rule set

​Create and inspect rule sets

​Assign and move rules

​Execution order

​Conflict-safe reordering

​Set-local stopping

​One event-start snapshot

​Event traces

​Simulation boundaries

​Recommended structure

The default rule set

Create and inspect rule sets

Assign and move rules

Execution order

Conflict-safe reordering

Set-local stopping

One event-start snapshot

Event traces

Simulation boundaries

Recommended structure