Create a reward
curl --request POST \
--url https://api.scrip.dev/v1/programs/{programId}/rewards \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"asset_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "$10 Gift Card",
"redemption_type": "UNIT_BASED",
"status": "DRAFT",
"unit_cost": "1000.00",
"available_from": "2024-01-01T00:00:00Z",
"available_until": "2024-12-31T23:59:59Z",
"category": "Gift Cards",
"description": "Redeemable for a $10 gift card",
"max_per_participant": 2,
"max_total": 100,
"metadata": {}
}
'import requests
url = "https://api.scrip.dev/v1/programs/{programId}/rewards"
payload = {
"asset_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "$10 Gift Card",
"redemption_type": "UNIT_BASED",
"status": "DRAFT",
"unit_cost": "1000.00",
"available_from": "2024-01-01T00:00:00Z",
"available_until": "2024-12-31T23:59:59Z",
"category": "Gift Cards",
"description": "Redeemable for a $10 gift card",
"max_per_participant": 2,
"max_total": 100,
"metadata": {}
}
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({
asset_id: '550e8400-e29b-41d4-a716-446655440000',
name: '$10 Gift Card',
redemption_type: 'UNIT_BASED',
status: 'DRAFT',
unit_cost: '1000.00',
available_from: '2024-01-01T00:00:00Z',
available_until: '2024-12-31T23:59:59Z',
category: 'Gift Cards',
description: 'Redeemable for a $10 gift card',
max_per_participant: 2,
max_total: 100,
metadata: {}
})
};
fetch('https://api.scrip.dev/v1/programs/{programId}/rewards', 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}/rewards",
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([
'asset_id' => '550e8400-e29b-41d4-a716-446655440000',
'name' => '$10 Gift Card',
'redemption_type' => 'UNIT_BASED',
'status' => 'DRAFT',
'unit_cost' => '1000.00',
'available_from' => '2024-01-01T00:00:00Z',
'available_until' => '2024-12-31T23:59:59Z',
'category' => 'Gift Cards',
'description' => 'Redeemable for a $10 gift card',
'max_per_participant' => 2,
'max_total' => 100,
'metadata' => [
]
]),
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}/rewards"
payload := strings.NewReader("{\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"name\": \"$10 Gift Card\",\n \"redemption_type\": \"UNIT_BASED\",\n \"status\": \"DRAFT\",\n \"unit_cost\": \"1000.00\",\n \"available_from\": \"2024-01-01T00:00:00Z\",\n \"available_until\": \"2024-12-31T23:59:59Z\",\n \"category\": \"Gift Cards\",\n \"description\": \"Redeemable for a $10 gift card\",\n \"max_per_participant\": 2,\n \"max_total\": 100,\n \"metadata\": {}\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}/rewards")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"name\": \"$10 Gift Card\",\n \"redemption_type\": \"UNIT_BASED\",\n \"status\": \"DRAFT\",\n \"unit_cost\": \"1000.00\",\n \"available_from\": \"2024-01-01T00:00:00Z\",\n \"available_until\": \"2024-12-31T23:59:59Z\",\n \"category\": \"Gift Cards\",\n \"description\": \"Redeemable for a $10 gift card\",\n \"max_per_participant\": 2,\n \"max_total\": 100,\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scrip.dev/v1/programs/{programId}/rewards")
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 \"asset_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"name\": \"$10 Gift Card\",\n \"redemption_type\": \"UNIT_BASED\",\n \"status\": \"DRAFT\",\n \"unit_cost\": \"1000.00\",\n \"available_from\": \"2024-01-01T00:00:00Z\",\n \"available_until\": \"2024-12-31T23:59:59Z\",\n \"category\": \"Gift Cards\",\n \"description\": \"Redeemable for a $10 gift card\",\n \"max_per_participant\": 2,\n \"max_total\": 100,\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"asset_id": "550e8400-e29b-41d4-a716-446655440002",
"auto_managed": false,
"available_from": "2024-01-01T00:00:00Z",
"available_until": "2024-12-31T23:59:59Z",
"category": "Gift Cards",
"committed_units": 42,
"created_at": "2024-01-15T10:30:00Z",
"delivered_units": 39,
"description": "Redeemable for a $10 gift card",
"display": {
"description_html": "<p>Use this gift card online or in store.</p>",
"disclosure_html": "<p>Valid in the United States.</p>",
"image_url": "https://images.example.com/gift-card.png",
"instructions_html": "<p>Present the gift card at checkout.</p>"
},
"face_currency": "USD",
"face_value_minor": 1000,
"fulfillment": {
"account_status": "ACTIVE",
"asset_scale": 2,
"countries": [
"US"
],
"currencies": [
"USD"
],
"delivery_method": "claim_link",
"denominations_minor": [
1000,
2500
],
"rate": "1.5",
"value_max_minor": 10000,
"value_min_minor": 500
},
"fulfillment_product_id": "550e8400-e29b-41d4-a716-446655440004",
"id": "550e8400-e29b-41d4-a716-446655440000",
"kind": "CUSTOM",
"max_per_participant": 2,
"max_total": 100,
"metadata": {},
"name": "$10 Gift Card",
"pending_units": 3,
"program_id": "550e8400-e29b-41d4-a716-446655440001",
"redemption_type": "UNIT_BASED",
"reward_source_id": "550e8400-e29b-41d4-a716-446655440003",
"status": "ACTIVE",
"unit_cost": "1000.00",
"updated_at": "2024-01-15T10:30:00Z"
}{
"code": "bad_request",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Invalid request parameters"
}{
"code": "unauthorized",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Missing or invalid credentials"
}{
"code": "not_found",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Resource not found"
}{
"code": "conflict",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Resource already exists or state conflict"
}{
"code": "unsupported_media_type",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Content-Type must be application/json"
}{
"code": "internal_error",
"message": "An internal error occurred"
}Rewards
Create a reward
Create a new reward in the program’s catalog.
POST
/
v1
/
programs
/
{programId}
/
rewards
Create a reward
curl --request POST \
--url https://api.scrip.dev/v1/programs/{programId}/rewards \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"asset_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "$10 Gift Card",
"redemption_type": "UNIT_BASED",
"status": "DRAFT",
"unit_cost": "1000.00",
"available_from": "2024-01-01T00:00:00Z",
"available_until": "2024-12-31T23:59:59Z",
"category": "Gift Cards",
"description": "Redeemable for a $10 gift card",
"max_per_participant": 2,
"max_total": 100,
"metadata": {}
}
'import requests
url = "https://api.scrip.dev/v1/programs/{programId}/rewards"
payload = {
"asset_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "$10 Gift Card",
"redemption_type": "UNIT_BASED",
"status": "DRAFT",
"unit_cost": "1000.00",
"available_from": "2024-01-01T00:00:00Z",
"available_until": "2024-12-31T23:59:59Z",
"category": "Gift Cards",
"description": "Redeemable for a $10 gift card",
"max_per_participant": 2,
"max_total": 100,
"metadata": {}
}
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({
asset_id: '550e8400-e29b-41d4-a716-446655440000',
name: '$10 Gift Card',
redemption_type: 'UNIT_BASED',
status: 'DRAFT',
unit_cost: '1000.00',
available_from: '2024-01-01T00:00:00Z',
available_until: '2024-12-31T23:59:59Z',
category: 'Gift Cards',
description: 'Redeemable for a $10 gift card',
max_per_participant: 2,
max_total: 100,
metadata: {}
})
};
fetch('https://api.scrip.dev/v1/programs/{programId}/rewards', 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}/rewards",
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([
'asset_id' => '550e8400-e29b-41d4-a716-446655440000',
'name' => '$10 Gift Card',
'redemption_type' => 'UNIT_BASED',
'status' => 'DRAFT',
'unit_cost' => '1000.00',
'available_from' => '2024-01-01T00:00:00Z',
'available_until' => '2024-12-31T23:59:59Z',
'category' => 'Gift Cards',
'description' => 'Redeemable for a $10 gift card',
'max_per_participant' => 2,
'max_total' => 100,
'metadata' => [
]
]),
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}/rewards"
payload := strings.NewReader("{\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"name\": \"$10 Gift Card\",\n \"redemption_type\": \"UNIT_BASED\",\n \"status\": \"DRAFT\",\n \"unit_cost\": \"1000.00\",\n \"available_from\": \"2024-01-01T00:00:00Z\",\n \"available_until\": \"2024-12-31T23:59:59Z\",\n \"category\": \"Gift Cards\",\n \"description\": \"Redeemable for a $10 gift card\",\n \"max_per_participant\": 2,\n \"max_total\": 100,\n \"metadata\": {}\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}/rewards")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"name\": \"$10 Gift Card\",\n \"redemption_type\": \"UNIT_BASED\",\n \"status\": \"DRAFT\",\n \"unit_cost\": \"1000.00\",\n \"available_from\": \"2024-01-01T00:00:00Z\",\n \"available_until\": \"2024-12-31T23:59:59Z\",\n \"category\": \"Gift Cards\",\n \"description\": \"Redeemable for a $10 gift card\",\n \"max_per_participant\": 2,\n \"max_total\": 100,\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scrip.dev/v1/programs/{programId}/rewards")
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 \"asset_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"name\": \"$10 Gift Card\",\n \"redemption_type\": \"UNIT_BASED\",\n \"status\": \"DRAFT\",\n \"unit_cost\": \"1000.00\",\n \"available_from\": \"2024-01-01T00:00:00Z\",\n \"available_until\": \"2024-12-31T23:59:59Z\",\n \"category\": \"Gift Cards\",\n \"description\": \"Redeemable for a $10 gift card\",\n \"max_per_participant\": 2,\n \"max_total\": 100,\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"asset_id": "550e8400-e29b-41d4-a716-446655440002",
"auto_managed": false,
"available_from": "2024-01-01T00:00:00Z",
"available_until": "2024-12-31T23:59:59Z",
"category": "Gift Cards",
"committed_units": 42,
"created_at": "2024-01-15T10:30:00Z",
"delivered_units": 39,
"description": "Redeemable for a $10 gift card",
"display": {
"description_html": "<p>Use this gift card online or in store.</p>",
"disclosure_html": "<p>Valid in the United States.</p>",
"image_url": "https://images.example.com/gift-card.png",
"instructions_html": "<p>Present the gift card at checkout.</p>"
},
"face_currency": "USD",
"face_value_minor": 1000,
"fulfillment": {
"account_status": "ACTIVE",
"asset_scale": 2,
"countries": [
"US"
],
"currencies": [
"USD"
],
"delivery_method": "claim_link",
"denominations_minor": [
1000,
2500
],
"rate": "1.5",
"value_max_minor": 10000,
"value_min_minor": 500
},
"fulfillment_product_id": "550e8400-e29b-41d4-a716-446655440004",
"id": "550e8400-e29b-41d4-a716-446655440000",
"kind": "CUSTOM",
"max_per_participant": 2,
"max_total": 100,
"metadata": {},
"name": "$10 Gift Card",
"pending_units": 3,
"program_id": "550e8400-e29b-41d4-a716-446655440001",
"redemption_type": "UNIT_BASED",
"reward_source_id": "550e8400-e29b-41d4-a716-446655440003",
"status": "ACTIVE",
"unit_cost": "1000.00",
"updated_at": "2024-01-15T10:30:00Z"
}{
"code": "bad_request",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Invalid request parameters"
}{
"code": "unauthorized",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Missing or invalid credentials"
}{
"code": "not_found",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Resource not found"
}{
"code": "conflict",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Resource already exists or state conflict"
}{
"code": "unsupported_media_type",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Content-Type must be application/json"
}{
"code": "internal_error",
"message": "An internal error occurred"
}Creates a new reward in a program’s catalog. A reward requires a
name, redemption_type, asset_id, unit_cost, and status. You can also include description, category, and a freeform metadata object.
The asset_id must reference an asset that is linked to the program. unit_cost must be a positive decimal string. Both redemption_type and asset_id are immutable after creation.
redemption_type controls how participants redeem: UNIT_BASED rewards are redeemed in discrete quantities with optional inventory caps (max_total, max_per_participant), while AMOUNT_BASED rewards allow variable amounts with no inventory limits.
Set available_from and available_until to define a redemption window (available_from must be before available_until). Most rewards should start in DRAFT status until configuration is finalized, then transition to ACTIVE when ready.
Reward names must be unique within a program. A 409 is returned with code name_exists if the name is already taken. Rewards cannot be created in archived programs.
For usage patterns and examples, see the Rewards Catalog guide.
Authorizations
ApiKeyAuthBearerAuth
API key passed in the X-API-Key header.
Path Parameters
Program ID
Body
application/json
Reward details
Asset used to price this reward (must be linked to the program). Immutable after creation.
Example:
"550e8400-e29b-41d4-a716-446655440000"
Display name for the reward
Required string length:
1 - 255Example:
"$10 Gift Card"
How the reward is redeemed: UNIT_BASED (discrete quantities) or AMOUNT_BASED (variable amounts). Immutable after creation.
Available options:
UNIT_BASED, AMOUNT_BASED Example:
"UNIT_BASED"
Lifecycle status: DRAFT, ACTIVE, OUT_OF_STOCK, or ARCHIVED
Available options:
DRAFT, ACTIVE, OUT_OF_STOCK, ARCHIVED Example:
"DRAFT"
Cost per unit in the reward's asset (decimal string for precision, must be positive)
Minimum string length:
1Example:
"1000.00"
Start of the availability window (RFC 3339, null if always available)
Example:
"2024-01-01T00:00:00Z"
End of the availability window (RFC 3339, null if no end date)
Example:
"2024-12-31T23:59:59Z"
Grouping label for organizing rewards in the catalog
Maximum string length:
100Example:
"Gift Cards"
Details about the reward
Maximum string length:
1000Example:
"Redeemable for a $10 gift card"
Per-participant redemption limit (UNIT_BASED only, null = unlimited)
Example:
2
Global inventory limit (UNIT_BASED only, null = unlimited)
Example:
100
Custom key-value data attached to this reward
Response
Reward created
A reward with its pricing, inventory, availability, and metadata
Asset used to price this reward
Example:
"550e8400-e29b-41d4-a716-446655440002"
Whether the catalog sync manages this item's lifecycle automatically
Example:
false
Start of the availability window (RFC 3339, null if always available)
Example:
"2024-01-01T00:00:00Z"
End of the availability window (RFC 3339, null if no end date)
Example:
"2024-12-31T23:59:59Z"
Grouping label for organizing rewards in the catalog
Example:
"Gift Cards"
UNIT_BASED units currently consuming inventory. Includes delivered and pending units. Null for AMOUNT_BASED rewards.
Example:
42
When this reward was created (RFC 3339)
Example:
"2024-01-15T10:30:00Z"
UNIT_BASED units whose redemption has been captured. Null for AMOUNT_BASED rewards.
Example:
39
Details about the reward
Example:
"Redeemable for a $10 gift card"
Product content for displaying a managed reward
Show child attributes
Show child attributes
ISO 4217 currency of the face value (PROVIDER items only)
Example:
"USD"
Pinned face value in minor units (fixed-denomination PROVIDER items only)
Example:
1000
Supported values, currencies, delivery, and pricing for managed rewards
Show child attributes
Show child attributes
Product ordered when this reward is redeemed. Present for managed rewards (kind PROVIDER).
Example:
"550e8400-e29b-41d4-a716-446655440004"
Unique identifier for this reward
Example:
"550e8400-e29b-41d4-a716-446655440000"
Whether you created the reward directly (CUSTOM) or Scrip manages it through a reward source (PROVIDER)
Example:
"CUSTOM"
Per-participant redemption limit (UNIT_BASED only, null = unlimited)
Example:
2
Global inventory limit (UNIT_BASED only, null = unlimited)
Example:
100
Custom key-value data attached to this reward
Display name for this reward
Example:
"$10 Gift Card"
UNIT_BASED units awaiting fulfillment. Null for AMOUNT_BASED rewards.
Example:
3
Program this reward belongs to
Example:
"550e8400-e29b-41d4-a716-446655440001"
How the reward is redeemed: UNIT_BASED (discrete quantities) or AMOUNT_BASED (variable amounts)
Example:
"UNIT_BASED"
Reward source that supplies this managed reward
Example:
"550e8400-e29b-41d4-a716-446655440003"
Lifecycle status: DRAFT, ACTIVE, OUT_OF_STOCK, or ARCHIVED
Example:
"ACTIVE"
Fixed price per unit. For variable-value managed rewards, use fulfillment.rate to calculate the charge.
Example:
"1000.00"
When this reward was last modified (RFC 3339)
Example:
"2024-01-15T10:30:00Z"