List rewards
curl --request GET \
--url https://api.scrip.dev/v1/programs/{programId}/rewards \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.scrip.dev/v1/programs/{programId}/rewards"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
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 => "GET",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://api.scrip.dev/v1/programs/{programId}/rewards"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.scrip.dev/v1/programs/{programId}/rewards")
.header("X-API-Key", "<api-key>")
.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::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": [
{
"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"
}
],
"pagination": {
"has_more": true,
"next_cursor": "YWJjMTIz"
}
}{
"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": "internal_error",
"message": "An internal error occurred"
}Running your program
List rewards
List rewards for a program.
GET
/
v1
/
programs
/
{programId}
/
rewards
List rewards
curl --request GET \
--url https://api.scrip.dev/v1/programs/{programId}/rewards \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.scrip.dev/v1/programs/{programId}/rewards"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
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 => "GET",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://api.scrip.dev/v1/programs/{programId}/rewards"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.scrip.dev/v1/programs/{programId}/rewards")
.header("X-API-Key", "<api-key>")
.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::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": [
{
"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"
}
],
"pagination": {
"has_more": true,
"next_cursor": "YWJjMTIz"
}
}{
"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": "internal_error",
"message": "An internal error occurred"
}List the custom and managed rewards in a program’s catalog. Use
An
status=ACTIVE to show active rewards in your application.
By default, the list excludes both rewards with status=ARCHIVED and soft-deleted rewards. This also applies when you omit the status filter. Pass include_archived=true to include both, or combine it with status=ARCHIVED to list only archived rewards.
An active reward is still subject to availability windows, participant limits, balance, account readiness, and program limits at redemption time. This endpoint does not check an individual participant’s eligibility.
Use reward_type=GIFT_CARD to show gift cards or reward_type=CUSTOM to show rewards you created yourself. Prepaid cards use PREPAID_CARD; donations use CHARITY. You can combine a type with asset_id, a partial category name, and redemption_type to narrow the catalog. All filters apply before pagination.
Use search to find rewards by name. For alphabetical order, set sort_by=name&sort_dir=asc; the API defaults to newest first. Follow pagination.next_cursor with the same filters and sorting to retrieve the next page. Start again without a cursor when changing the view.
See Rewards catalog for custom rewards and Gift cards for showing and redeeming cards.
Managed rewards
Managed rewards havekind: "PROVIDER" and auto_managed: true. Their category identifies GIFT_CARD, PREPAID_CARD, or CHARITY. reward_source_id and fulfillment_product_id identify their configuration; use the reward’s own id when redeeming.
The same fields are returned by Get a reward.
| Field | Use |
|---|---|
display | Optional image_url, description_html, disclosure_html, and instructions_html. Sanitize HTML before rendering. |
fulfillment.countries | Countries supported by the product. |
fulfillment.currencies | Currencies accepted when redeeming. |
fulfillment.denominations_minor | Supported fixed card values, in currency minor units. |
fulfillment.value_min_minor, fulfillment.value_max_minor | Inclusive range of accepted card values. A value can match this range or the fixed-value list. |
fulfillment.rate | Asset units per currency minor unit for a variable-value reward. The same numeric rate applies to all supported currencies; no currency conversion occurs. |
fulfillment.asset_scale | Number of decimal places supported by the payment asset. Round the calculated price up to this precision. |
face_currency | Default currency when a variable-value redemption omits currency. |
unit_cost | Final asset price for a fixed-value UNIT_BASED reward. |
AMOUNT_BASED gift card lets the participant choose a supported value. A fixed list of denominations alone does not make it UNIT_BASED. Setting one fixed value and currency in product settings creates a UNIT_BASED reward, whose fulfillment details contain only that value and currency.Authorizations
ApiKeyAuthBearerAuth
API key passed in the X-API-Key header.
Path Parameters
Program ID
Query Parameters
Filter by reward status
Available options:
DRAFT, ACTIVE, OUT_OF_STOCK, ARCHIVED Filter by reward type, independent of the fulfillment account
Available options:
CUSTOM, GIFT_CARD, PREPAID_CARD, CHARITY Filter by the asset used to pay for the reward
Filter by category (case-insensitive partial match)
Filter by redemption method
Available options:
UNIT_BASED, AMOUNT_BASED Include archived and soft-deleted rewards in results
Search by reward name (partial match)
Sort field
Available options:
created_at, name Sort direction
Available options:
asc, desc Maximum number of results (default 50, max 200)
Required range:
x >= 1Pagination cursor from previous response