Skip to main content
POST
/
v1
/
programs
/
{programId}
/
tiers
Create a tier
curl --request POST \
  --url https://api.scrip.dev/v1/programs/{programId}/tiers \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "key": "status",
  "levels": [
    {
      "key": "gold",
      "rank": 2,
      "benefits": {},
      "color": "#FFD700",
      "display_name": "Gold",
      "icon_url": "<string>",
      "qualification": {}
    }
  ],
  "display_name": "Loyalty Status",
  "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"
}
Creates a new tier within a program. A tier is a ranked progression track where participants hold exactly one level at a time. Every tier needs a unique key and at least one level. Each level has its own key and a rank that sets its position in the hierarchy (higher rank = higher tier). Both the tier key and level key are immutable after creation. Keys must be lowercase alphanumeric with underscores, starting with a letter.

​
Lifecycle

The lifecycle object controls how the tier behaves over time. Omit it to create a rules-only tier where changes are driven entirely by SET_TIER rule actions or direct API calls. When present, lifecycle has four parts:
  • retention controls whether the tier is re-evaluated on a periodic schedule (PERIOD_BASED) or expires after a duration of inactivity (ACTIVITY_REFRESH). With ACTIVITY_REFRESH, each event processed for the participant resets the timer.
  • qualification_period sets the evaluation cycle for PERIOD_BASED retention: CALENDAR_YEAR (Jan 1 to Dec 31), FIXED_YEAR (custom start date via start_month and start_day), or NONE.
  • downgrade_policy determines what happens when qualification lapses. DROP_TO_QUALIFYING re-evaluates and drops to the highest level the participant still qualifies for. DROP_ONE drops exactly one rank. HOLD keeps the current level indefinitely. Set grace_days to defer downgrades and min_level to establish a floor.
  • counters controls whether qualifying counters reset to zero (NONE) or carry over the excess above the current level’s threshold (EXCESS) at period end. The qualifying array lists which counter keys are subject to rollover.

​
Qualification

Each level can define qualification criteria for counter-based auto-advancement. After rules fire for an event, Scrip evaluates each level’s thresholds and upgrades the participant to the highest level they qualify for. Set mode to ALL (every criterion must pass) or ANY (at least one). Each criterion checks a counter key against a threshold using an operator: >=, >, ==, <=, or <. Auto-qualification only upgrades. Downgrades happen through the lifecycle system at period end or timer expiration.

​
Benefits

benefits is a freeform JSON object on each level. Scrip stores it and returns it with the participant’s tier state. Use it to drive behavior in your application, like a points_multiplier, free_shipping flag, or discount_percent. Scrip does not interpret the benefits payload. It is a data contract between your tier configuration and your application.
For full examples, lifecycle walkthroughs, and tier state in CEL expressions, 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

Body

application/json

Tier definition with at least one level

​
key
string
required

Unique identifier for this tier within the program (immutable after creation, lowercase alphanumeric + underscores)

Required string length: 1 - 100
Pattern: ^[a-z][a-z0-9_]*$
Example:

"status"

​
levels
object[]
required

Ordered set of levels within this tier (at least one required)

Minimum array length: 1
​
display_name
string

Human-readable name shown in dashboards and reports

Maximum string length: 255
Example:

"Loyalty Status"

​
lifecycle
object

Controls how tiers behave over time: retention mode, qualification period, downgrade policy, and counter rollover. Omit for rules-only mode.

Response

Tier created

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"