Skip to main content
PATCH
/
v1
/
participants
/
{id}
/
status
Update participant state
curl --request PATCH \
  --url https://api.scrip.dev/v1/participants/{id}/status \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "status": "SUSPENDED"
}
'
{
  "attributes": {
    "plan": "premium",
    "region": "us-east"
  },
  "balances": [
    {
      "asset_id": "550e8400-e29b-41d4-a716-446655440000",
      "available": "1500.00",
      "deferred": "0.00",
      "held": "200.00"
    }
  ],
  "counters": {
    "points_earned": "1500",
    "purchases": "42"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "external_id": "user_123",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "program_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "status": "ACTIVE",
  "tags": [
    "vip"
  ],
  "tiers": {
    "loyalty": {
      "level": "gold",
      "rank": 2
    }
  },
  "updated_at": "2024-01-15T10:30:00Z"
}
Changes a participant’s lifecycle status.
  • ACTIVE — the participant can earn and spend normally
  • SUSPENDED — temporarily frozen. Financial actions (CREDIT, DEBIT, HOLD, RELEASE, FORFEIT, COUNTER) are blocked. Metadata actions (TAG, SET_ATTRIBUTE, SET_TIER) are still allowed. Reversible by setting status back to ACTIVE
  • CLOSED — deactivated. Same restrictions as SUSPENDED. Can be transitioned back to ACTIVE or SUSPENDED
When a rule triggers a blocked action against a suspended or closed participant, that action fails and the event is marked FAILED. Events where only allowed actions match will still complete successfully.
For the full breakdown of which actions are allowed by status, see Participants — What’s allowed by status.

Authorizations

​
X-API-Key
string
header
required

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

Path Parameters

​
id
string<uuid>
required

Participant ID

Body

application/json

State update

​
status
enum<string>
required

Lifecycle state

Available options:
ACTIVE,
SUSPENDED,
CLOSED
Example:

"SUSPENDED"

Response

Participant updated

​
attributes
object

Key-value metadata. Each key is accessible in rules as participant.attributes.{key}

Example:
{ "plan": "premium", "region": "us-east" }
​
balances
object[]

Current balances per asset, split by bucket

​
counters
object

Numeric accumulators, returned as strings for precision

Example:
{
  "points_earned": "1500",
  "purchases": "42"
}
​
created_at
string<date-time>

When the participant was created

Example:

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

​
external_id
string

Your application's identifier for this user

Example:

"user_123"

​
id
string<uuid>

Participant ID

Example:

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

​
program_ids
string[]

Programs this participant is enrolled in

Example:
["550e8400-e29b-41d4-a716-446655440000"]
​
status
string

Lifecycle state

Example:

"ACTIVE"

​
tags
string[]

Labels for segmentation, accessible in rules as participant.tags

Example:
["vip"]
​
tiers
object

Current tier level per tier type

Example:
{ "loyalty": { "level": "gold", "rank": 2 } }
​
updated_at
string<date-time>

When the participant was last modified

Example:

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