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": "https://example.com/icons/gold.png",
      "qualification": {
        "criteria": [
          {
            "counter": "nights",
            "operator": ">=",
            "threshold": 25
          }
        ],
        "mode": "ALL"
      }
    }
  ],
  "display_name": "Loyalty Status",
  "lifecycle": {
    "counters": {
      "qualifying": [
        "<string>"
      ],
      "rollover": "EXCESS"
    },
    "status_validity": {
      "extend_months": 1
    }
  }
}
'
import requests

url = "https://api.scrip.dev/v1/programs/{programId}/tiers"

payload = {
    "key": "status",
    "levels": [
        {
            "key": "gold",
            "rank": 2,
            "benefits": {},
            "color": "#FFD700",
            "display_name": "Gold",
            "icon_url": "https://example.com/icons/gold.png",
            "qualification": {
                "criteria": [
                    {
                        "counter": "nights",
                        "operator": ">=",
                        "threshold": 25
                    }
                ],
                "mode": "ALL"
            }
        }
    ],
    "display_name": "Loyalty Status",
    "lifecycle": {
        "counters": {
            "qualifying": ["<string>"],
            "rollover": "EXCESS"
        },
        "status_validity": { "extend_months": 1 }
    }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    key: 'status',
    levels: [
      {
        key: 'gold',
        rank: 2,
        benefits: {},
        color: '#FFD700',
        display_name: 'Gold',
        icon_url: 'https://example.com/icons/gold.png',
        qualification: {criteria: [{counter: 'nights', operator: '>=', threshold: 25}], mode: 'ALL'}
      }
    ],
    display_name: 'Loyalty Status',
    lifecycle: {
      counters: {qualifying: ['<string>'], rollover: 'EXCESS'},
      status_validity: {extend_months: 1}
    }
  })
};

fetch('https://api.scrip.dev/v1/programs/{programId}/tiers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.scrip.dev/v1/programs/{programId}/tiers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'key' => 'status',
    'levels' => [
        [
                'key' => 'gold',
                'rank' => 2,
                'benefits' => [
                                
                ],
                'color' => '#FFD700',
                'display_name' => 'Gold',
                'icon_url' => 'https://example.com/icons/gold.png',
                'qualification' => [
                                'criteria' => [
                                                                [
                                                                                                                                'counter' => 'nights',
                                                                                                                                'operator' => '>=',
                                                                                                                                'threshold' => 25
                                                                ]
                                ],
                                'mode' => 'ALL'
                ]
        ]
    ],
    'display_name' => 'Loyalty Status',
    'lifecycle' => [
        'counters' => [
                'qualifying' => [
                                '<string>'
                ],
                'rollover' => 'EXCESS'
        ],
        'status_validity' => [
                'extend_months' => 1
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.scrip.dev/v1/programs/{programId}/tiers"

	payload := strings.NewReader("{\n  \"key\": \"status\",\n  \"levels\": [\n    {\n      \"key\": \"gold\",\n      \"rank\": 2,\n      \"benefits\": {},\n      \"color\": \"#FFD700\",\n      \"display_name\": \"Gold\",\n      \"icon_url\": \"https://example.com/icons/gold.png\",\n      \"qualification\": {\n        \"criteria\": [\n          {\n            \"counter\": \"nights\",\n            \"operator\": \">=\",\n            \"threshold\": 25\n          }\n        ],\n        \"mode\": \"ALL\"\n      }\n    }\n  ],\n  \"display_name\": \"Loyalty Status\",\n  \"lifecycle\": {\n    \"counters\": {\n      \"qualifying\": [\n        \"<string>\"\n      ],\n      \"rollover\": \"EXCESS\"\n    },\n    \"status_validity\": {\n      \"extend_months\": 1\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.scrip.dev/v1/programs/{programId}/tiers")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"key\": \"status\",\n  \"levels\": [\n    {\n      \"key\": \"gold\",\n      \"rank\": 2,\n      \"benefits\": {},\n      \"color\": \"#FFD700\",\n      \"display_name\": \"Gold\",\n      \"icon_url\": \"https://example.com/icons/gold.png\",\n      \"qualification\": {\n        \"criteria\": [\n          {\n            \"counter\": \"nights\",\n            \"operator\": \">=\",\n            \"threshold\": 25\n          }\n        ],\n        \"mode\": \"ALL\"\n      }\n    }\n  ],\n  \"display_name\": \"Loyalty Status\",\n  \"lifecycle\": {\n    \"counters\": {\n      \"qualifying\": [\n        \"<string>\"\n      ],\n      \"rollover\": \"EXCESS\"\n    },\n    \"status_validity\": {\n      \"extend_months\": 1\n    }\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.scrip.dev/v1/programs/{programId}/tiers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"key\": \"status\",\n  \"levels\": [\n    {\n      \"key\": \"gold\",\n      \"rank\": 2,\n      \"benefits\": {},\n      \"color\": \"#FFD700\",\n      \"display_name\": \"Gold\",\n      \"icon_url\": \"https://example.com/icons/gold.png\",\n      \"qualification\": {\n        \"criteria\": [\n          {\n            \"counter\": \"nights\",\n            \"operator\": \">=\",\n            \"threshold\": 25\n          }\n        ],\n        \"mode\": \"ALL\"\n      }\n    }\n  ],\n  \"display_name\": \"Loyalty Status\",\n  \"lifecycle\": {\n    \"counters\": {\n      \"qualifying\": [\n        \"<string>\"\n      ],\n      \"rollover\": \"EXCESS\"\n    },\n    \"status_validity\": {\n      \"extend_months\": 1\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "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": "https://example.com/icons/gold.png",
      "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": "90d"
    },
    "status_validity": {
      "extend_months": 1
    }
  },
  "program_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "ACTIVE",
  "updated_at": "2024-01-15T10:30:00Z"
}
{
  "code": "bad_request",
  "details": {
    "expected": "uuid",
    "field": "asset_id",
    "fields": [
      {
        "expected": "<unknown>",
        "field": "amount",
        "message": "This field is required",
        "reason": "required",
        "received": "-10.00"
      }
    ],
    "reason": "invalid",
    "received": "not-a-uuid"
  },
  "message": "Invalid request parameters"
}
{
  "code": "unauthorized",
  "details": {
    "expected": "uuid",
    "field": "asset_id",
    "fields": [
      {
        "expected": "<unknown>",
        "field": "amount",
        "message": "This field is required",
        "reason": "required",
        "received": "-10.00"
      }
    ],
    "reason": "invalid",
    "received": "not-a-uuid"
  },
  "message": "Missing or invalid credentials"
}
{
  "code": "not_found",
  "details": {
    "expected": "uuid",
    "field": "asset_id",
    "fields": [
      {
        "expected": "<unknown>",
        "field": "amount",
        "message": "This field is required",
        "reason": "required",
        "received": "-10.00"
      }
    ],
    "reason": "invalid",
    "received": "not-a-uuid"
  },
  "message": "Resource not found"
}
{
  "code": "conflict",
  "details": {
    "expected": "uuid",
    "field": "asset_id",
    "fields": [
      {
        "expected": "<unknown>",
        "field": "amount",
        "message": "This field is required",
        "reason": "required",
        "received": "-10.00"
      }
    ],
    "reason": "invalid",
    "received": "not-a-uuid"
  },
  "message": "Resource already exists or state conflict"
}
{
  "code": "unsupported_media_type",
  "details": {
    "expected": "uuid",
    "field": "asset_id",
    "fields": [
      {
        "expected": "<unknown>",
        "field": "amount",
        "message": "This field is required",
        "reason": "required",
        "received": "-10.00"
      }
    ],
    "reason": "invalid",
    "received": "not-a-uuid"
  },
  "message": "Content-Type must be application/json"
}
{
  "code": "internal_error",
  "message": "An internal error occurred"
}
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 (periodic re-evaluation or activity-based expiry), qualification_period (the evaluation cycle for period-based retention), status_validity (extends a status grant past period end), downgrade_policy (what happens when qualification lapses; defaults to DROP_TO_QUALIFYING), and counters (whether qualifying counters reset or carry over excess at period end). The Tiers guide covers each object’s fields and behavior.

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