Skip to main content
PUT
/
v1
/
participants
/
{id}
/
state
/
tiers
/
{key}
Set participant tier
curl --request PUT \
  --url https://api.scrip.dev/v1/participants/{id}/state/tiers/{key} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "level": "<string>",
  "expires_at": "2023-11-07T05:31:56Z"
}
'
{
  "acquired_at": "2024-06-01T00:00:00Z",
  "benefits": {
    "discount_pct": 10,
    "free_shipping": true
  },
  "expires_at": "2025-06-01T00:00:00Z",
  "level": "gold",
  "rank": 2
}
Sets a participant’s tier level directly. The key path parameter identifies which tier to update (e.g., status), and program_id is required as a query parameter. The request body must include a level matching a defined level key on the tier. You can optionally provide an expires_at timestamp (RFC 3339) to schedule automatic removal of the tier assignment. The participant must be active and enrolled in the specified program. The program must also be active.
For usage patterns and examples, see the Tiers guide.

Authorizations

​
X-API-Key
string
header
required

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

Path Parameters

​
id
string<uuid>
required

Participant ID

​
key
string
required

Tier key (e.g., status)

Query Parameters

​
program_id
string<uuid>
required

Program ID

Body

application/json

Tier level to set

​
level
string
required

Key of the level to assign (e.g., gold)

Required string length: 1 - 100
​
expires_at
string<date-time>

When this tier assignment expires (RFC 3339, null for no expiration)

Response

Updated tier state

​
acquired_at
string<date-time>

When this tier level was earned

Example:

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

​
benefits
object

Benefits granted by this tier level

Example:
{ "discount_pct": 10, "free_shipping": true }
​
expires_at
string<date-time>

When this tier level expires

Example:

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

​
level
string

Current tier level name

Example:

"gold"

​
rank
integer

Numeric rank within the tier (higher = better)

Example:

2