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

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

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

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

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

fetch('https://api.scrip.dev/v1/programs/{programId}/tiers/{key}', 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/{key}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'display_name' => 'Loyalty Status',
    'levels' => [
        [
                'key' => 'gold',
                'benefits' => [
                                
                ],
                'color' => '#FFD700',
                'display_name' => 'Gold',
                'icon_url' => 'https://example.com/icons/gold.png',
                'qualification' => [
                                'criteria' => [
                                                                [
                                                                                                                                'counter' => 'nights',
                                                                                                                                'operator' => '>=',
                                                                                                                                'threshold' => 25
                                                                ]
                                ],
                                'mode' => 'ALL'
                ],
                'rank' => 2
        ]
    ],
    '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/{key}"

	payload := strings.NewReader("{\n  \"display_name\": \"Loyalty Status\",\n  \"levels\": [\n    {\n      \"key\": \"gold\",\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      \"rank\": 2\n    }\n  ],\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("PATCH", 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.patch("https://api.scrip.dev/v1/programs/{programId}/tiers/{key}")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"display_name\": \"Loyalty Status\",\n  \"levels\": [\n    {\n      \"key\": \"gold\",\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      \"rank\": 2\n    }\n  ],\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/{key}")

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

request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"display_name\": \"Loyalty Status\",\n  \"levels\": [\n    {\n      \"key\": \"gold\",\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      \"rank\": 2\n    }\n  ],\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"
}
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
Example:

"Loyalty Status"

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