Redeem a catalog item
curl --request POST \
--url https://api.scrip.dev/v1/participants/{id}/redemptions/items \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"reward_id": "550e8400-e29b-41d4-a716-446655440001",
"amount": "50.00",
"capture": false,
"description": "Gift card redemption",
"expected_amount": "50.00",
"expires_at": "2024-01-15T11:30:00Z",
"fulfillment": {
"currency": "USD",
"face_value_minor": 2500
},
"idempotency_key": "redeem-item-12345",
"quantity": 2,
"ttl_seconds": 3600
}
'import requests
url = "https://api.scrip.dev/v1/participants/{id}/redemptions/items"
payload = {
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"reward_id": "550e8400-e29b-41d4-a716-446655440001",
"amount": "50.00",
"capture": False,
"description": "Gift card redemption",
"expected_amount": "50.00",
"expires_at": "2024-01-15T11:30:00Z",
"fulfillment": {
"currency": "USD",
"face_value_minor": 2500
},
"idempotency_key": "redeem-item-12345",
"quantity": 2,
"ttl_seconds": 3600
}
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({
program_id: '550e8400-e29b-41d4-a716-446655440000',
reward_id: '550e8400-e29b-41d4-a716-446655440001',
amount: '50.00',
capture: false,
description: 'Gift card redemption',
expected_amount: '50.00',
expires_at: '2024-01-15T11:30:00Z',
fulfillment: {currency: 'USD', face_value_minor: 2500},
idempotency_key: 'redeem-item-12345',
quantity: 2,
ttl_seconds: 3600
})
};
fetch('https://api.scrip.dev/v1/participants/{id}/redemptions/items', 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}/redemptions/items",
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([
'program_id' => '550e8400-e29b-41d4-a716-446655440000',
'reward_id' => '550e8400-e29b-41d4-a716-446655440001',
'amount' => '50.00',
'capture' => false,
'description' => 'Gift card redemption',
'expected_amount' => '50.00',
'expires_at' => '2024-01-15T11:30:00Z',
'fulfillment' => [
'currency' => 'USD',
'face_value_minor' => 2500
],
'idempotency_key' => 'redeem-item-12345',
'quantity' => 2,
'ttl_seconds' => 3600
]),
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}/redemptions/items"
payload := strings.NewReader("{\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"reward_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"amount\": \"50.00\",\n \"capture\": false,\n \"description\": \"Gift card redemption\",\n \"expected_amount\": \"50.00\",\n \"expires_at\": \"2024-01-15T11:30:00Z\",\n \"fulfillment\": {\n \"currency\": \"USD\",\n \"face_value_minor\": 2500\n },\n \"idempotency_key\": \"redeem-item-12345\",\n \"quantity\": 2,\n \"ttl_seconds\": 3600\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/participants/{id}/redemptions/items")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"reward_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"amount\": \"50.00\",\n \"capture\": false,\n \"description\": \"Gift card redemption\",\n \"expected_amount\": \"50.00\",\n \"expires_at\": \"2024-01-15T11:30:00Z\",\n \"fulfillment\": {\n \"currency\": \"USD\",\n \"face_value_minor\": 2500\n },\n \"idempotency_key\": \"redeem-item-12345\",\n \"quantity\": 2,\n \"ttl_seconds\": 3600\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scrip.dev/v1/participants/{id}/redemptions/items")
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 \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"reward_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"amount\": \"50.00\",\n \"capture\": false,\n \"description\": \"Gift card redemption\",\n \"expected_amount\": \"50.00\",\n \"expires_at\": \"2024-01-15T11:30:00Z\",\n \"fulfillment\": {\n \"currency\": \"USD\",\n \"face_value_minor\": 2500\n },\n \"idempotency_key\": \"redeem-item-12345\",\n \"quantity\": 2,\n \"ttl_seconds\": 3600\n}"
response = http.request(request)
puts response.read_body{
"amount": "1000.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440003",
"capture_journal_entry_id": "550e8400-e29b-41d4-a716-446655440007",
"captured_at": "2024-01-15T10:45:00Z",
"created_at": "2024-01-15T10:30:00Z",
"description": "Redeemed: Gift Card",
"expires_at": "2024-01-15T11:30:00Z",
"failure_reason": "fulfillment_failed",
"fulfillment": {
"claim_url": "https://claim.example.com/abc123",
"created_at": "2024-01-15T10:30:00Z",
"face_currency": "USD",
"face_value_minor": 2500,
"failure_reason": "provider_permanent_error",
"provider": "TREMENDOUS",
"provider_order_id": "ord_abc123",
"resolved_at": "2024-01-15T10:45:00Z",
"status": "PROCESSING",
"updated_at": "2024-01-15T10:30:00Z"
},
"id": "550e8400-e29b-41d4-a716-446655440000",
"journal_entry_id": "550e8400-e29b-41d4-a716-446655440005",
"participant_id": "550e8400-e29b-41d4-a716-446655440002",
"program_id": "550e8400-e29b-41d4-a716-446655440001",
"quantity": 2,
"release_journal_entry_id": "550e8400-e29b-41d4-a716-446655440008",
"released_amount": "1000.00",
"reservation_id": "550e8400-e29b-41d4-a716-446655440006",
"resolved_at": "2024-01-15T10:45:00Z",
"reversed_amount": "0.00",
"reversed_quantity": 0,
"reward_id": "550e8400-e29b-41d4-a716-446655440004",
"status": "COMPLETED",
"unit_cost": "500.00",
"updated_at": "2024-01-15T10:30:00Z"
}{
"amount": "1000.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440003",
"capture_journal_entry_id": "550e8400-e29b-41d4-a716-446655440007",
"captured_at": "2024-01-15T10:45:00Z",
"created_at": "2024-01-15T10:30:00Z",
"description": "Redeemed: Gift Card",
"expires_at": "2024-01-15T11:30:00Z",
"failure_reason": "fulfillment_failed",
"fulfillment": {
"claim_url": "https://claim.example.com/abc123",
"created_at": "2024-01-15T10:30:00Z",
"face_currency": "USD",
"face_value_minor": 2500,
"failure_reason": "provider_permanent_error",
"provider": "TREMENDOUS",
"provider_order_id": "ord_abc123",
"resolved_at": "2024-01-15T10:45:00Z",
"status": "PROCESSING",
"updated_at": "2024-01-15T10:30:00Z"
},
"id": "550e8400-e29b-41d4-a716-446655440000",
"journal_entry_id": "550e8400-e29b-41d4-a716-446655440005",
"participant_id": "550e8400-e29b-41d4-a716-446655440002",
"program_id": "550e8400-e29b-41d4-a716-446655440001",
"quantity": 2,
"release_journal_entry_id": "550e8400-e29b-41d4-a716-446655440008",
"released_amount": "1000.00",
"reservation_id": "550e8400-e29b-41d4-a716-446655440006",
"resolved_at": "2024-01-15T10:45:00Z",
"reversed_amount": "0.00",
"reversed_quantity": 0,
"reward_id": "550e8400-e29b-41d4-a716-446655440004",
"status": "COMPLETED",
"unit_cost": "500.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": "unprocessable",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Business rule violation"
}{
"code": "internal_error",
"message": "An internal error occurred"
}Running your program
Redeem a catalog item
Redeem a reward catalog item for a participant. Capture immediately or authorize into a PENDING redemption backed by a ledger reservation.
POST
/
v1
/
participants
/
{id}
/
redemptions
/
items
Redeem a catalog item
curl --request POST \
--url https://api.scrip.dev/v1/participants/{id}/redemptions/items \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"reward_id": "550e8400-e29b-41d4-a716-446655440001",
"amount": "50.00",
"capture": false,
"description": "Gift card redemption",
"expected_amount": "50.00",
"expires_at": "2024-01-15T11:30:00Z",
"fulfillment": {
"currency": "USD",
"face_value_minor": 2500
},
"idempotency_key": "redeem-item-12345",
"quantity": 2,
"ttl_seconds": 3600
}
'import requests
url = "https://api.scrip.dev/v1/participants/{id}/redemptions/items"
payload = {
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"reward_id": "550e8400-e29b-41d4-a716-446655440001",
"amount": "50.00",
"capture": False,
"description": "Gift card redemption",
"expected_amount": "50.00",
"expires_at": "2024-01-15T11:30:00Z",
"fulfillment": {
"currency": "USD",
"face_value_minor": 2500
},
"idempotency_key": "redeem-item-12345",
"quantity": 2,
"ttl_seconds": 3600
}
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({
program_id: '550e8400-e29b-41d4-a716-446655440000',
reward_id: '550e8400-e29b-41d4-a716-446655440001',
amount: '50.00',
capture: false,
description: 'Gift card redemption',
expected_amount: '50.00',
expires_at: '2024-01-15T11:30:00Z',
fulfillment: {currency: 'USD', face_value_minor: 2500},
idempotency_key: 'redeem-item-12345',
quantity: 2,
ttl_seconds: 3600
})
};
fetch('https://api.scrip.dev/v1/participants/{id}/redemptions/items', 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}/redemptions/items",
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([
'program_id' => '550e8400-e29b-41d4-a716-446655440000',
'reward_id' => '550e8400-e29b-41d4-a716-446655440001',
'amount' => '50.00',
'capture' => false,
'description' => 'Gift card redemption',
'expected_amount' => '50.00',
'expires_at' => '2024-01-15T11:30:00Z',
'fulfillment' => [
'currency' => 'USD',
'face_value_minor' => 2500
],
'idempotency_key' => 'redeem-item-12345',
'quantity' => 2,
'ttl_seconds' => 3600
]),
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}/redemptions/items"
payload := strings.NewReader("{\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"reward_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"amount\": \"50.00\",\n \"capture\": false,\n \"description\": \"Gift card redemption\",\n \"expected_amount\": \"50.00\",\n \"expires_at\": \"2024-01-15T11:30:00Z\",\n \"fulfillment\": {\n \"currency\": \"USD\",\n \"face_value_minor\": 2500\n },\n \"idempotency_key\": \"redeem-item-12345\",\n \"quantity\": 2,\n \"ttl_seconds\": 3600\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/participants/{id}/redemptions/items")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"reward_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"amount\": \"50.00\",\n \"capture\": false,\n \"description\": \"Gift card redemption\",\n \"expected_amount\": \"50.00\",\n \"expires_at\": \"2024-01-15T11:30:00Z\",\n \"fulfillment\": {\n \"currency\": \"USD\",\n \"face_value_minor\": 2500\n },\n \"idempotency_key\": \"redeem-item-12345\",\n \"quantity\": 2,\n \"ttl_seconds\": 3600\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scrip.dev/v1/participants/{id}/redemptions/items")
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 \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"reward_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"amount\": \"50.00\",\n \"capture\": false,\n \"description\": \"Gift card redemption\",\n \"expected_amount\": \"50.00\",\n \"expires_at\": \"2024-01-15T11:30:00Z\",\n \"fulfillment\": {\n \"currency\": \"USD\",\n \"face_value_minor\": 2500\n },\n \"idempotency_key\": \"redeem-item-12345\",\n \"quantity\": 2,\n \"ttl_seconds\": 3600\n}"
response = http.request(request)
puts response.read_body{
"amount": "1000.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440003",
"capture_journal_entry_id": "550e8400-e29b-41d4-a716-446655440007",
"captured_at": "2024-01-15T10:45:00Z",
"created_at": "2024-01-15T10:30:00Z",
"description": "Redeemed: Gift Card",
"expires_at": "2024-01-15T11:30:00Z",
"failure_reason": "fulfillment_failed",
"fulfillment": {
"claim_url": "https://claim.example.com/abc123",
"created_at": "2024-01-15T10:30:00Z",
"face_currency": "USD",
"face_value_minor": 2500,
"failure_reason": "provider_permanent_error",
"provider": "TREMENDOUS",
"provider_order_id": "ord_abc123",
"resolved_at": "2024-01-15T10:45:00Z",
"status": "PROCESSING",
"updated_at": "2024-01-15T10:30:00Z"
},
"id": "550e8400-e29b-41d4-a716-446655440000",
"journal_entry_id": "550e8400-e29b-41d4-a716-446655440005",
"participant_id": "550e8400-e29b-41d4-a716-446655440002",
"program_id": "550e8400-e29b-41d4-a716-446655440001",
"quantity": 2,
"release_journal_entry_id": "550e8400-e29b-41d4-a716-446655440008",
"released_amount": "1000.00",
"reservation_id": "550e8400-e29b-41d4-a716-446655440006",
"resolved_at": "2024-01-15T10:45:00Z",
"reversed_amount": "0.00",
"reversed_quantity": 0,
"reward_id": "550e8400-e29b-41d4-a716-446655440004",
"status": "COMPLETED",
"unit_cost": "500.00",
"updated_at": "2024-01-15T10:30:00Z"
}{
"amount": "1000.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440003",
"capture_journal_entry_id": "550e8400-e29b-41d4-a716-446655440007",
"captured_at": "2024-01-15T10:45:00Z",
"created_at": "2024-01-15T10:30:00Z",
"description": "Redeemed: Gift Card",
"expires_at": "2024-01-15T11:30:00Z",
"failure_reason": "fulfillment_failed",
"fulfillment": {
"claim_url": "https://claim.example.com/abc123",
"created_at": "2024-01-15T10:30:00Z",
"face_currency": "USD",
"face_value_minor": 2500,
"failure_reason": "provider_permanent_error",
"provider": "TREMENDOUS",
"provider_order_id": "ord_abc123",
"resolved_at": "2024-01-15T10:45:00Z",
"status": "PROCESSING",
"updated_at": "2024-01-15T10:30:00Z"
},
"id": "550e8400-e29b-41d4-a716-446655440000",
"journal_entry_id": "550e8400-e29b-41d4-a716-446655440005",
"participant_id": "550e8400-e29b-41d4-a716-446655440002",
"program_id": "550e8400-e29b-41d4-a716-446655440001",
"quantity": 2,
"release_journal_entry_id": "550e8400-e29b-41d4-a716-446655440008",
"released_amount": "1000.00",
"reservation_id": "550e8400-e29b-41d4-a716-446655440006",
"resolved_at": "2024-01-15T10:45:00Z",
"reversed_amount": "0.00",
"reversed_quantity": 0,
"reward_id": "550e8400-e29b-41d4-a716-446655440004",
"status": "COMPLETED",
"unit_cost": "500.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": "unprocessable",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Business rule violation"
}{
"code": "internal_error",
"message": "An internal error occurred"
}Creates a redemption for a reward in the program catalog. For custom
For fixed-value cards, include the reviewed
UNIT_BASED rewards, specify quantity (defaults to 1); for AMOUNT_BASED rewards, specify amount. Set capture: true to capture immediately, capture: false to authorize into PENDING, or omit it to use the program’s fulfillment_mode.
Instant capture debits AVAILABLE and credits the redemption target in one REDEMPTION journal entry. Authorization moves the calculated cost to HELD in a HOLD journal entry and returns reservation_id plus the effective expires_at. Use expires_at or ttl_seconds to bound a pending redemption; they are mutually exclusive. For custom UNIT_BASED rewards, both paths commit catalog inventory immediately, so committed_units includes units still awaiting fulfillment.
Pass an idempotency_key to safely retry requests. Duplicate requests return 200 with the existing redemption instead of 201.
To protect a price shown before confirmation, send expected_amount as the total cost in asset units. Scrip compares it with the calculated cost before reserving or spending assets. A mismatch returns 409 reward_price_changed without creating a redemption. Refresh the catalog and confirm the new cost before submitting again. A retry of an existing redemption compares against its original amount; a different expected amount returns 409 idempotency_conflict.
Gift cards
Includefulfillment to order the selected gift card. Scrip reserves the cost, places the order, and captures the balance after the order succeeds. This applies regardless of the program’s fulfillment_mode; capture: true returns 422 fulfillment_capture_conflict.
| Request field | Behavior |
|---|---|
fulfillment.face_value_minor | Chosen card value for an AMOUNT_BASED reward. Must match a supported denomination or fall within the supported range. |
fulfillment.currency | One of the supported currencies. If omitted for a variable-value reward, defaults to the reward’s face_currency. |
fulfillment: {} | Uses the configured value and currency of a fixed-value UNIT_BASED reward. Any supplied values must match. |
amount | Omit for gift cards. Scrip calculates the asset charge. |
quantity | Omit or set to 1. Each redemption orders one card. |
fulfillment.face_value_minor and fulfillment.currency as well as expected_amount. If the configured value or currency changed, Scrip returns 422 fulfillment_face_value_mismatch before placing an order.
The request waits up to about 30 seconds for the order to finish. Send Prefer: respond-async to return immediately. HTTP 201 means the redemption was created; check the response’s status for its outcome.
A successful response may include fulfillment.claim_url. If the link is missing, use Create a claim link for the same redemption. Retrying the original request with its idempotency key returns the existing redemption and may wait again for the outcome.
For deadline selection and resolution endpoints, see the Redemption lifecycle guide. For committed, pending, and delivered inventory, see Rewards Catalog. For a complete gift-card example, see Gift cards.
Authorizations
ApiKeyAuthBearerAuth
API key passed in the X-API-Key header.
Path Parameters
Participant ID
Body
application/json
Catalog item redemption details
The program this redemption belongs to
Example:
"550e8400-e29b-41d4-a716-446655440000"
The reward catalog item to redeem
Example:
"550e8400-e29b-41d4-a716-446655440001"
Asset amount for custom AMOUNT_BASED rewards. For managed rewards, supply fulfillment.face_value_minor instead.
Example:
"50.00"
Whether to capture immediately. True completes instantly, false authorizes, and omission uses the program fulfillment_mode.
Example:
false
Optional context for this redemption, used in journal entries (max 500 chars)
Example:
"Gift card redemption"
Expected total cost in asset units. If the current cost differs, no redemption is created (409 reward_price_changed). Retries compare against the original redemption's amount.
Example:
"50.00"
Absolute pending-redemption deadline (RFC3339); alternative to ttl_seconds and limited to one year. If no request or program deadline is set, the authorization defaults to 90 days.
Example:
"2024-01-15T11:30:00Z"
Order details for managed rewards. Required when the reward includes fulfillment; capture: true is unsupported.
Show child attributes
Show child attributes
Prevents duplicate redemptions when retrying requests
Example:
"redeem-item-12345"
Number of units to redeem. Defaults to 1; managed rewards require exactly 1.
Example:
2
Relative pending-redemption deadline in seconds; alternative to expires_at and limited to one year. If no request or program deadline is set, the authorization defaults to 90 days.
Example:
3600
Response
Duplicate request (idempotency key matched, returns existing record)
Total amount debited from the participant's balance (decimal string)
Example:
"1000.00"
The asset that was debited
Example:
"550e8400-e29b-41d4-a716-446655440003"
Ledger entry that captured a pending redemption
Example:
"550e8400-e29b-41d4-a716-446655440007"
When the pending redemption was captured
Example:
"2024-01-15T10:45:00Z"
When this redemption was created
Example:
"2024-01-15T10:30:00Z"
Context for this redemption, used in journal entries
Example:
"Redeemed: Gift Card"
Effective deadline of the backing reservation. Always present for pending redemptions; defaults to 90 days and may be configured up to one year.
Example:
"2024-01-15T11:30:00Z"
Machine-readable or operator-supplied terminal failure detail
Example:
"fulfillment_failed"
Gift-card vendor order status, present only for provider-backed (fulfillment) redemptions
Show child attributes
Show child attributes
Unique identifier for this redemption
Example:
"550e8400-e29b-41d4-a716-446655440000"
Immutable ledger anchor: the hold entry for pending redemptions, otherwise the instant redemption entry
Example:
"550e8400-e29b-41d4-a716-446655440005"
The participant who redeemed
Example:
"550e8400-e29b-41d4-a716-446655440002"
The program this redemption belongs to
Example:
"550e8400-e29b-41d4-a716-446655440001"
Number of units redeemed (catalog redemptions only)
Example:
2
Ledger entry that released a pending redemption's reserved value back to AVAILABLE. Present only on FAILED and CANCELLED redemptions whose reservation resolved RELEASED; null while PENDING, after capture (see capture_journal_entry_id), and when every reserved lot had already expired before release (the reservation resolved EXPIRED and no release entry was posted).
Example:
"550e8400-e29b-41d4-a716-446655440008"
Amount the release entry returned to AVAILABLE (decimal string). Equals the authorized amount unless part of the reserved value expired before release, in which case only the live remainder is reported. Present exactly when release_journal_entry_id is present.
Example:
"1000.00"
Reservation backing a pending redemption
Example:
"550e8400-e29b-41d4-a716-446655440006"
When the pending redemption reached a terminal state
Example:
"2024-01-15T10:45:00Z"
Cumulative amount reversed so far (decimal string)
Example:
"0.00"
Cumulative units reversed so far (UNIT_BASED catalog redemptions only)
Example:
0
The reward catalog item that was redeemed (catalog redemptions only)
Example:
"550e8400-e29b-41d4-a716-446655440004"
Current lifecycle and reversal state
Available options:
PENDING, COMPLETED, FAILED, CANCELLED, PARTIALLY_REVERSED, FULLY_REVERSED Example:
"COMPLETED"
Cost per unit at the time of redemption (catalog redemptions only, decimal string)
Example:
"500.00"
When this redemption was last updated (e.g., after a reversal)
Example:
"2024-01-15T10:30:00Z"