Set participant tier
curl --request PUT \
--url https://api.scrip.dev/v1/participants/{id}/state/tiers/{key} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"level": "gold",
"expires_at": "2024-12-31T23:59:59Z"
}
'import requests
url = "https://api.scrip.dev/v1/participants/{id}/state/tiers/{key}"
payload = {
"level": "gold",
"expires_at": "2024-12-31T23:59:59Z"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({level: 'gold', expires_at: '2024-12-31T23:59:59Z'})
};
fetch('https://api.scrip.dev/v1/participants/{id}/state/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/participants/{id}/state/tiers/{key}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'level' => 'gold',
'expires_at' => '2024-12-31T23:59:59Z'
]),
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/participants/{id}/state/tiers/{key}"
payload := strings.NewReader("{\n \"level\": \"gold\",\n \"expires_at\": \"2024-12-31T23:59:59Z\"\n}")
req, _ := http.NewRequest("PUT", 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.put("https://api.scrip.dev/v1/participants/{id}/state/tiers/{key}")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"level\": \"gold\",\n \"expires_at\": \"2024-12-31T23:59:59Z\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scrip.dev/v1/participants/{id}/state/tiers/{key}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"level\": \"gold\",\n \"expires_at\": \"2024-12-31T23:59:59Z\"\n}"
response = http.request(request)
puts response.read_body{
"acquired_at": "2024-06-01T00:00:00Z",
"benefits": {
"discount_pct": 10,
"free_shipping": true
},
"expires_at": "2025-06-01T00:00:00Z",
"level": "gold",
"rank": 2
}{
"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"
}State
Set participant tier
Directly set a participant’s tier to a specific level, optionally with an expiration.
PUT
/
v1
/
participants
/
{id}
/
state
/
tiers
/
{key}
Set participant tier
curl --request PUT \
--url https://api.scrip.dev/v1/participants/{id}/state/tiers/{key} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"level": "gold",
"expires_at": "2024-12-31T23:59:59Z"
}
'import requests
url = "https://api.scrip.dev/v1/participants/{id}/state/tiers/{key}"
payload = {
"level": "gold",
"expires_at": "2024-12-31T23:59:59Z"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({level: 'gold', expires_at: '2024-12-31T23:59:59Z'})
};
fetch('https://api.scrip.dev/v1/participants/{id}/state/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/participants/{id}/state/tiers/{key}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'level' => 'gold',
'expires_at' => '2024-12-31T23:59:59Z'
]),
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/participants/{id}/state/tiers/{key}"
payload := strings.NewReader("{\n \"level\": \"gold\",\n \"expires_at\": \"2024-12-31T23:59:59Z\"\n}")
req, _ := http.NewRequest("PUT", 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.put("https://api.scrip.dev/v1/participants/{id}/state/tiers/{key}")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"level\": \"gold\",\n \"expires_at\": \"2024-12-31T23:59:59Z\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scrip.dev/v1/participants/{id}/state/tiers/{key}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"level\": \"gold\",\n \"expires_at\": \"2024-12-31T23:59:59Z\"\n}"
response = http.request(request)
puts response.read_body{
"acquired_at": "2024-06-01T00:00:00Z",
"benefits": {
"discount_pct": 10,
"free_shipping": true
},
"expires_at": "2025-06-01T00:00:00Z",
"level": "gold",
"rank": 2
}{
"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"
}Sets a participant’s tier level directly. The
key path parameter identifies which tier to update (e.g., status), and program_id is required as a query parameter.
The request body must include a level matching a defined level key on the tier. You can optionally provide an expires_at timestamp (RFC 3339) to schedule automatic removal of the tier assignment. Any existing expiration task for this tier is replaced.
The participant must be active and enrolled in the specified program. The program must also be active. Inactive participants return 409 Conflict with code participant_inactive.
For usage patterns and examples, see the Tiers guide.
Authorizations
ApiKeyAuthBearerAuth
API key passed in the X-API-Key header.
Query Parameters
Program ID
Body
application/json
Tier level to set
Response
Updated tier state
When this tier level was earned
Example:
"2024-06-01T00:00:00Z"
Benefits granted by this tier level
Show child attributes
Show child attributes
Example:
{ "discount_pct": 10, "free_shipping": true }
When this tier level expires
Example:
"2025-06-01T00:00:00Z"
Current tier level name
Example:
"gold"
Numeric rank within the tier (higher = better)
Example:
2
⌘I