Skip to main content
Tags, counters, attributes, and tiers store state on participants, programs, and groups. Rules read this state in CEL conditions and update it through actions. Tiers are covered in their own guide. See Tiers for qualification, retention, and downgrade policies. Ledger balances are separate from state, but conditions can read them through participant.balance.<symbol>. See CEL Expressions.

​
Tags

Boolean flags. A tag either exists on an entity or it doesn’t. Useful for one-time gates, status markers, and segmentation labels. 
# Add a tag
PUT /v1/participants/{id}/state/tags/vip

# Remove a tag
DELETE /v1/participants/{id}/state/tags/vip

# List all tags
GET /v1/participants/{id}/state/tags
Tags are trimmed and de-duplicated on write, stored verbatim, and matched case-sensitively in CEL: "VIP" and "vip" are different tags. Pick one casing convention and use it consistently; these docs use lowercase.

​
Using tags in conditions

// Check if tagged
"vip" in participant.tags

// One-time gate
!("welcome_bonus" in participant.tags)

// Multiple tags
sets.contains(participant.tags, ["vip", "gold"])      // has ALL
sets.intersects(participant.tags, ["vip", "silver"])   // has ANY

​
Setting tags from rules

The TAG action adds a tag and UNTAG removes one. Both apply to the event’s participant by default. This rule grants a one-time welcome bonus and tags the participant to prevent re-triggering: 
{
  "name": "Welcome Bonus",
  "condition": "event.type == 'signup' && !('welcome_bonus' in participant.tags)",
  "actions": [
    {"type": "CREDIT", "asset_id": "...", "amount": "100"},
    {"type": "TAG", "tag": "welcome_bonus"}
  ]
}
Use UNTAG to remove a tag when a condition is no longer met. This rule removes a promotional flag when the promo period ends: 
{"type": "UNTAG", "tag": "promo_active"}
To tag or untag a different entity, add a target: 
{"type": "TAG", "tag": "milestone_reached", "target": {"type": "PROGRAM"}}
{"type": "UNTAG", "tag": "milestone_reached", "target": {"type": "PROGRAM"}}

​
Counters

Numeric accumulators. Stored as high-precision decimals, available as numbers in CEL expressions. Useful for running totals, occurrence counts, and threshold tracking. 
# Set a counter
PUT /v1/participants/{id}/state/counters/lifetime_spend
{"value": "500.00"}

# Increment a counter
POST /v1/participants/{id}/state/counters/lifetime_spend/increment
{"delta": "49.99"}

# Get a counter
GET /v1/participants/{id}/state/counters/lifetime_spend

# Delete a counter
DELETE /v1/participants/{id}/state/counters/lifetime_spend
PUT sets an absolute value and is last-write-wins; increment adds delta atomically, so concurrent writers never lose updates, and negative deltas decrement. See Increment participant counter.

​
Using counters in conditions

Prefer the dot-access shorthand: a missing counter defaults to 0, so no get() is needed: 
// Simple threshold
participant.counter.purchase_count >= 10

// Threshold crossing detection
participant.counter.spend < 1000.0 &&
(participant.counter.spend + event.amount) >= 1000.0

​
Updating counters from rules

The COUNTER action increments the current value. It does not replace it. This rule tracks purchase count and lifetime spend on every purchase: 
{
  "name": "Track Purchase Activity",
  "condition": "event.type == 'purchase'",
  "actions": [
    {"type": "COUNTER", "key": "purchase_count", "value": "1"},
    {"type": "COUNTER", "key": "lifetime_spend", "value": "${{ event.amount }}"}
  ]
}
If a participant has purchase_count: 7 and lifetime_spend: 340.00, and a purchase event arrives with event.amount: 49.99, after this rule fires:
  • purchase_count becomes 8
  • lifetime_spend becomes 389.99
The value field accepts static values ("1") or ${{ }} CEL expressions ("${{ event.amount }}").
Counters reflect the pre-event state during rule evaluation. If Rule A increments a counter, Rule B in the same event still sees the original value. The same applies to tags, attributes, and tiers: state actions are durable updates, not same-event condition inputs. See State Snapshot Evaluation Behavior for details.

​
Auto-resetting counters

Counters can be configured to automatically reset to 0 after a duration elapses. The timer is per-participant, starting from when the counter was last created, explicitly set, or auto-reset. Resets are applied on the next read or write, not at the exact moment the timer expires. Set reset_after via the API: 
PUT /v1/participants/{id}/state/counters/monthly_purchases
{"value": "1", "reset_after": "30d"}
Or from a rule action: 
{"type": "COUNTER", "key": "monthly_purchases", "value": "1", "reset_after": "30d"}
The duration accepts the Go units s, m, and h plus d (days) and w (weeks), combinable as in "1w2d12h"; "30d" and "720h" are equivalent. Note that m means minutes, not months. Each participant gets their own independent timer. Reading the counter returns the effective value (0 if the window has elapsed), along with reset_after and last_reset_at when auto-reset is configured. To remove auto-reset from a counter, set reset_after to an empty string. Omitting the field leaves the existing configuration unchanged. This is for per-participant elapsed-time windows: “reset purchase count 30 days after first purchase” or “daily counter that resets after 24h of inactivity.” For calendar-aligned resets (every Sunday, 1st of month), use a cron automation instead.

​
Attributes

Key-value strings for arbitrary metadata. Useful for segmentation, preferences, and profile data referenced in rules. 
# Set a single attribute
PUT /v1/participants/{id}/state/attributes/region
{"value": "US"}

# Update multiple attributes
PATCH /v1/participants/{id}/state/attributes
{"attributes": {"region": "US", "plan": "premium"}}

# Get an attribute
GET /v1/participants/{id}/state/attributes/region

# Remove an attribute
DELETE /v1/participants/{id}/state/attributes/region

​
Using attributes in conditions

participant.attribute.region == "US"
participant.attribute.plan in ["premium", "enterprise"]

​
Setting attributes from rules

The SET_ATTRIBUTE action sets a key-value pair on the event’s participant. Unmarked values are always stored as literal strings: "high" is stored as the text high. For dynamic values, wrap CEL in ${{ ... }}: "value": "${{ event.category }}" stores the evaluated result. 
{
  "name": "Mark High Spender",
  "condition": "event.type == 'purchase' && event.amount >= 500",
  "actions": [
    {"type": "SET_ATTRIBUTE", "key": "spender_tier", "value": "high"},
    {"type": "SET_ATTRIBUTE", "key": "last_category", "value": "${{ event.category }}"}
  ]
}

​
Program and Group State

Programs and groups support the same state types as participants. Access them in CEL via program.* and groups[*].*. 
// Program counter
program.counter.total_issued < 100000

// Program tag
"milestone_reached" in program.tags
To update program or group state from a rule, add a target to the action: 
{
  "name": "Limited Giveaway",
  "condition": "event.type == 'claim' && program.counter.total_claims < 1000.0",
  "actions": [
    {"type": "CREDIT", "asset_id": "...", "amount": "50"},
    {"type": "COUNTER", "key": "total_claims", "value": "1", "target": {"type": "PROGRAM"}}
  ]
}

​
State History

All state changes are logged. Query the history to see what changed, when, and why: 
GET /v1/participants/{id}/activity/state-history?state_type=counter&key=lifetime_spend
Each entry records the state_type, key, operation (set or delete), old_value, new_value, timestamp, and the source of the change. Rule-triggered changes include the event_id. Direct API calls include the API key ID.

​
State Updates on Inactive Participants

State update behavior depends on participant status:
State TypeACTIVESUSPENDED / CLOSED
TagsAllowedAllowed
AttributesAllowedAllowed
CountersAllowedBlocked (409 error)