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": {
        "criteria": [
          {
            "counter": "nights",
            "operator": ">=",
            "threshold": 25
          }
        ],
        "mode": "ALL"
      },
      "rank": 2
    }
  ],
  "lifecycle": {
    "counters": {
      "qualifying": [
        "<string>"
      ],
      "rollover": "EXCESS"
    },
    "status_validity": {
      "extend_months": 1
    }
  }
}
'
{
  "archived_at": "2024-03-01T00:00:00Z",
  "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": {
        "criteria": [
          {
            "counter": "nights",
            "operator": ">=",
            "threshold": 25
          }
        ],
        "mode": "ALL"
      },
      "rank": 2,
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "lifecycle": {
    "counters": {
      "qualifying": [
        "<string>"
      ],
      "rollover": "EXCESS"
    },
    "downgrade_policy": {
      "mode": "DROP_ONE",
      "grace_days": 30,
      "min_level": "silver"
    },
    "qualification_period": {
      "type": "FIXED_YEAR",
      "start_day": 1,
      "start_month": 2
    },
    "retention": {
      "mode": "ACTIVITY_REFRESH",
      "duration": "2160h"
    },
    "status_validity": {
      "extend_months": 1
    }
  },
  "program_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "ACTIVE",
  "updated_at": "2024-01-15T10:30:00Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.scrip.dev/llms.txt

Use this file to discover all available pages before exploring further.

Partially 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. You can update display_name, rank, color, icon_url, benefits, and qualification on existing levels. New keys create new levels (rank is required for new levels). A 409 is returned if a level key or rank conflicts with an existing level. 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. Tiers in archived programs cannot be updated.

​
Clearing configuration

The lifecycle object and a level’s qualification object distinguish two cases on update:
  • Omitting the field, or sending null, leaves the stored config unchanged.
  • Sending an empty object ({}) clears it. "lifecycle": {} turns the tier rules-only. "qualification": {} removes a level’s auto-advancement.
A populated object replaces the stored config entirely. It is not deep-merged, so include every field you want to keep.
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

​
archived_at
string<date-time>

When the tier was archived (RFC 3339); absent while the tier is ACTIVE

Example:

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

​
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"

​
status
string

Lifecycle status: ACTIVE, or ARCHIVED once the tier has been archived

Example:

"ACTIVE"

​
updated_at
string<date-time>

When this tier was last modified (RFC 3339)

Example:

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