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": {
        "criteria": [
          {
            "counter": "nights",
            "operator": ">=",
            "threshold": 25
          }
        ],
        "mode": "ALL"
      }
    }
  ],
  "display_name": "Loyalty Status",
  "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.

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 (pattern: ^[a-z][a-z0-9_]*$). Each level can also include color (hex code for UI display), icon_url, and a freeform benefits object. Tiers cannot be created under an archived program.

​
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 five 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.
  • status_validity extends a status grant past the period end. extend_months keeps status valid for that many months beyond the boundary. 0 or omitted means status expires exactly at period end.
  • 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. Omit the whole object to default to DROP_TO_QUALIFYING.
  • 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 <. threshold defaults to 0 when omitted, so set it explicitly for a meaningful criterion. 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: 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

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