Update a program

curl --request PATCH \
  --url https://api.scrip.dev/v1/programs/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "description": "Updated description",
  "fulfillment_mode": "ASYNC",
  "name": "Updated Program Name",
  "on_unknown_participant": "REJECT",
  "pending_redemption_ttl": "24h",
  "redemption_target_entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "redemption_target_type": "LEDGER_ENTITY",
  "status": "SUSPENDED"
}
'

import requests

url = "https://api.scrip.dev/v1/programs/{id}"

payload = {
    "description": "Updated description",
    "fulfillment_mode": "ASYNC",
    "name": "Updated Program Name",
    "on_unknown_participant": "REJECT",
    "pending_redemption_ttl": "24h",
    "redemption_target_entity_id": "550e8400-e29b-41d4-a716-446655440000",
    "redemption_target_type": "LEDGER_ENTITY",
    "status": "SUSPENDED"
}
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({
    description: 'Updated description',
    fulfillment_mode: 'ASYNC',
    name: 'Updated Program Name',
    on_unknown_participant: 'REJECT',
    pending_redemption_ttl: '24h',
    redemption_target_entity_id: '550e8400-e29b-41d4-a716-446655440000',
    redemption_target_type: 'LEDGER_ENTITY',
    status: 'SUSPENDED'
  })
};

fetch('https://api.scrip.dev/v1/programs/{id}', 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/{id}",
  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([
    'description' => 'Updated description',
    'fulfillment_mode' => 'ASYNC',
    'name' => 'Updated Program Name',
    'on_unknown_participant' => 'REJECT',
    'pending_redemption_ttl' => '24h',
    'redemption_target_entity_id' => '550e8400-e29b-41d4-a716-446655440000',
    'redemption_target_type' => 'LEDGER_ENTITY',
    'status' => 'SUSPENDED'
  ]),
  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/{id}"

	payload := strings.NewReader("{\n  \"description\": \"Updated description\",\n  \"fulfillment_mode\": \"ASYNC\",\n  \"name\": \"Updated Program Name\",\n  \"on_unknown_participant\": \"REJECT\",\n  \"pending_redemption_ttl\": \"24h\",\n  \"redemption_target_entity_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"redemption_target_type\": \"LEDGER_ENTITY\",\n  \"status\": \"SUSPENDED\"\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/{id}")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"description\": \"Updated description\",\n  \"fulfillment_mode\": \"ASYNC\",\n  \"name\": \"Updated Program Name\",\n  \"on_unknown_participant\": \"REJECT\",\n  \"pending_redemption_ttl\": \"24h\",\n  \"redemption_target_entity_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"redemption_target_type\": \"LEDGER_ENTITY\",\n  \"status\": \"SUSPENDED\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.scrip.dev/v1/programs/{id}")

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  \"description\": \"Updated description\",\n  \"fulfillment_mode\": \"ASYNC\",\n  \"name\": \"Updated Program Name\",\n  \"on_unknown_participant\": \"REJECT\",\n  \"pending_redemption_ttl\": \"24h\",\n  \"redemption_target_entity_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"redemption_target_type\": \"LEDGER_ENTITY\",\n  \"status\": \"SUSPENDED\"\n}"

response = http.request(request)
puts response.read_body

{
  "created_at": "2024-01-15T10:30:00Z",
  "deleted_at": "2024-06-01T00:00:00Z",
  "description": "Quarterly sales incentive program",
  "fulfillment_mode": "INSTANT",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Q1 Sales Bonus",
  "on_unknown_participant": "CREATE",
  "pending_redemption_ttl": "24h",
  "redemption_target_entity_id": "550e8400-e29b-41d4-a716-446655440002",
  "redemption_target_type": "SYSTEM_REDEMPTION",
  "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": "forbidden",
  "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": "Insufficient permissions for this action"
}

{
  "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": "unprocessable",
  "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": "Business rule violation"
}

{
  "code": "internal_error",
  "message": "An internal error occurred"
}

PATCH

programs

{id}

Update a program

curl --request PATCH \
  --url https://api.scrip.dev/v1/programs/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "description": "Updated description",
  "fulfillment_mode": "ASYNC",
  "name": "Updated Program Name",
  "on_unknown_participant": "REJECT",
  "pending_redemption_ttl": "24h",
  "redemption_target_entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "redemption_target_type": "LEDGER_ENTITY",
  "status": "SUSPENDED"
}
'

import requests

url = "https://api.scrip.dev/v1/programs/{id}"

payload = {
    "description": "Updated description",
    "fulfillment_mode": "ASYNC",
    "name": "Updated Program Name",
    "on_unknown_participant": "REJECT",
    "pending_redemption_ttl": "24h",
    "redemption_target_entity_id": "550e8400-e29b-41d4-a716-446655440000",
    "redemption_target_type": "LEDGER_ENTITY",
    "status": "SUSPENDED"
}
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({
    description: 'Updated description',
    fulfillment_mode: 'ASYNC',
    name: 'Updated Program Name',
    on_unknown_participant: 'REJECT',
    pending_redemption_ttl: '24h',
    redemption_target_entity_id: '550e8400-e29b-41d4-a716-446655440000',
    redemption_target_type: 'LEDGER_ENTITY',
    status: 'SUSPENDED'
  })
};

fetch('https://api.scrip.dev/v1/programs/{id}', 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/{id}",
  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([
    'description' => 'Updated description',
    'fulfillment_mode' => 'ASYNC',
    'name' => 'Updated Program Name',
    'on_unknown_participant' => 'REJECT',
    'pending_redemption_ttl' => '24h',
    'redemption_target_entity_id' => '550e8400-e29b-41d4-a716-446655440000',
    'redemption_target_type' => 'LEDGER_ENTITY',
    'status' => 'SUSPENDED'
  ]),
  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/{id}"

	payload := strings.NewReader("{\n  \"description\": \"Updated description\",\n  \"fulfillment_mode\": \"ASYNC\",\n  \"name\": \"Updated Program Name\",\n  \"on_unknown_participant\": \"REJECT\",\n  \"pending_redemption_ttl\": \"24h\",\n  \"redemption_target_entity_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"redemption_target_type\": \"LEDGER_ENTITY\",\n  \"status\": \"SUSPENDED\"\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/{id}")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"description\": \"Updated description\",\n  \"fulfillment_mode\": \"ASYNC\",\n  \"name\": \"Updated Program Name\",\n  \"on_unknown_participant\": \"REJECT\",\n  \"pending_redemption_ttl\": \"24h\",\n  \"redemption_target_entity_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"redemption_target_type\": \"LEDGER_ENTITY\",\n  \"status\": \"SUSPENDED\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.scrip.dev/v1/programs/{id}")

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  \"description\": \"Updated description\",\n  \"fulfillment_mode\": \"ASYNC\",\n  \"name\": \"Updated Program Name\",\n  \"on_unknown_participant\": \"REJECT\",\n  \"pending_redemption_ttl\": \"24h\",\n  \"redemption_target_entity_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"redemption_target_type\": \"LEDGER_ENTITY\",\n  \"status\": \"SUSPENDED\"\n}"

response = http.request(request)
puts response.read_body

{
  "created_at": "2024-01-15T10:30:00Z",
  "deleted_at": "2024-06-01T00:00:00Z",
  "description": "Quarterly sales incentive program",
  "fulfillment_mode": "INSTANT",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Q1 Sales Bonus",
  "on_unknown_participant": "CREATE",
  "pending_redemption_ttl": "24h",
  "redemption_target_entity_id": "550e8400-e29b-41d4-a716-446655440002",
  "redemption_target_type": "SYSTEM_REDEMPTION",
  "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": "forbidden",
  "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": "Insufficient permissions for this action"
}

{
  "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": "unprocessable",
  "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": "Business rule violation"
}

{
  "code": "internal_error",
  "message": "An internal error occurred"
}

Updates a program’s name, description, on_unknown_participant, status, or redemption target configuration. Only include the fields you want to change; omitted fields are left unchanged. Status can be set to ACTIVE, SUSPENDED, or ARCHIVED. A SUSPENDED program preserves all data but stops event processing: event submissions can still be accepted for async validation, then fail with program_inactive. An ARCHIVED program has the same event-processing behavior and is hidden from list results. While a program is ARCHIVED, you can still update name and description, or reactivate the program by setting status to ACTIVE or SUSPENDED. Behavioral configuration changes are blocked while archived and return 409 with code program_archived. This includes on_unknown_participant, redemption_target_type, and redemption_target_entity_id. Setting redemption_target_type to LEDGER_ENTITY requires redemption_target_entity_id in the same request. Setting it to SYSTEM_REDEMPTION or SYSTEM_BREAKAGE must omit redemption_target_entity_id and clears any existing reference. Changes only affect redemptions created after the update: existing redemptions and their reversals continue to use the target captured at the time they were created.

For usage patterns and examples, see the Programs guide. For redemption target options, see Redemption Targets.

Authorizations

X-API-Key

string

header

required

API key passed in the X-API-Key header.

Path Parameters

string<uuid>

required

Program ID

Body

application/json

Fields to update

description

string

Program description

Maximum string length: 1000

Example:

"Updated description"

fulfillment_mode

enum<string>

Default redemption behavior when capture is omitted

Available options:

INSTANT,

ASYNC

Example:

"ASYNC"

name

string

Program name

Required string length: 1 - 255

Example:

"Updated Program Name"

on_unknown_participant

enum<string>

How to handle events for unregistered participants

Available options:

CREATE,

REJECT

Example:

"REJECT"

pending_redemption_ttl

string | null

Optional program-specific bound between 60 seconds and one year. Explicit null clears it; without a request or program bound, pending redemptions default to 90 days.

Example:

"24h"

redemption_target_entity_id

string<uuid>

Target ledger entity ID. Required when redemption_target_type is LEDGER_ENTITY; must be omitted for the SYSTEM_* targets.

Example:

"550e8400-e29b-41d4-a716-446655440000"

redemption_target_type

enum<string>

Where redeemed value is posted. One of SYSTEM_REDEMPTION, SYSTEM_BREAKAGE, LEDGER_ENTITY. The paired example shows LEDGER_ENTITY because that is the only target type that pairs with redemption_target_entity_id; SYSTEM_* targets must omit it.

Available options:

SYSTEM_REDEMPTION,

SYSTEM_BREAKAGE,

LEDGER_ENTITY

Example:

"LEDGER_ENTITY"

status

enum<string>

Lifecycle state

Available options:

ACTIVE,

SUSPENDED,

ARCHIVED

Example:

"SUSPENDED"

Response

Updated program

created_at

string<date-time>

When the program was created

Example:

"2024-01-15T10:30:00Z"

deleted_at

string<date-time>

Set when the program is archived

Example:

"2024-06-01T00:00:00Z"

description

string

Optional program description

Example:

"Quarterly sales incentive program"

fulfillment_mode

enum<string>

Default redemption behavior when capture is omitted

Available options:

INSTANT,

ASYNC

Example:

"INSTANT"

string<uuid>

Program ID

Example:

"550e8400-e29b-41d4-a716-446655440000"

name

string

Program name

Example:

"Q1 Sales Bonus"

on_unknown_participant

string

How events for unregistered participants are handled

Example:

"CREATE"

pending_redemption_ttl

string

Optional program-specific bound between 60 seconds and one year. Without a request or program bound, pending redemptions default to 90 days.

Example:

"24h"

redemption_target_entity_id

string<uuid>

Target ledger entity ID. Present only when redemption_target_type is LEDGER_ENTITY.

Example:

"550e8400-e29b-41d4-a716-446655440002"

redemption_target_type

string

Where redeemed value is posted: SYSTEM_REDEMPTION, SYSTEM_BREAKAGE, or LEDGER_ENTITY

Example:

"SYSTEM_REDEMPTION"

status

string

Lifecycle state

Example:

"ACTIVE"

updated_at

string<date-time>

When the program was last modified

Example:

"2024-01-15T10:30:00Z"

Scrip API

Endpoints

Update a program

Authorizations

Path Parameters

Body

Response