Skip to main content
PATCH
/
v1
/
programs
/
{programId}
/
tiers
/
{key}
Update a tier
curl --request PATCH \
  --url https://api.scrip.dev/v1/programs/{programId}/tiers/{key} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "display_name": "<string>",
  "levels": [
    {
      "key": "gold",
      "benefits": {},
      "color": "<string>",
      "display_name": "<string>",
      "icon_url": "<string>",
      "qualification": {},
      "rank": 2
    }
  ],
  "lifecycle": {}
}
'
{
  "created_at": "2024-01-15T10:30:00Z",
  "display_name": "Loyalty Status",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "status",
  "levels": [
    {
      "benefits": {},
      "color": "#FFD700",
      "created_at": "2024-01-15T10:30:00Z",
      "display_name": "Gold",
      "icon_url": "<string>",
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "key": "gold",
      "qualification": {},
      "rank": 2,
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "lifecycle": {},
  "program_id": "550e8400-e29b-41d4-a716-446655440001",
  "updated_at": "2024-01-15T10:30:00Z"
}
Updates a tier’s configuration. You can modify display_name, lifecycle settings, and levels. Only the fields you include in the request body are changed; omitted fields are left as-is. When updating levels, existing levels are matched by key and updated in place. New keys create new levels (a rank is required for new levels). Changes to qualification thresholds take effect for future evaluations but do not retroactively re-evaluate participants who have already qualified. The tier key is immutable and cannot be changed after creation.
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

​
programId
string<uuid>
required

Program ID

​
key
string
required

Tier key

Body

application/json

Fields to update

​
display_name
string

Human-readable name shown in dashboards and reports

Maximum string length: 255
​
levels
object[]

Levels to upsert. Existing levels (matched by key) are updated; new keys create new levels.

​
lifecycle
object

Lifecycle configuration updates (retention mode, qualification period, downgrade policy, counter rollover)

Response

Updated tier

A tier definition with its levels, lifecycle configuration, and metadata

​
created_at
string<date-time>

When this tier was created (RFC 3339)

Example:

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

​
display_name
string

Human-readable name

Example:

"Loyalty Status"

​
id
string<uuid>

Unique identifier for this tier

Example:

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

​
key
string

Tier key used in API calls and rule actions

Example:

"status"

​
levels
object[]

Ordered list of levels within this tier

​
lifecycle
object

Lifecycle configuration (retention mode, qualification period, downgrade policy, counter rollover)

​
program_id
string<uuid>

Program this tier belongs to

Example:

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

​
updated_at
string<date-time>

When this tier was last modified (RFC 3339)

Example:

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