Skip to main content
PATCH
/
v1
/
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",
  "name": "Updated Program Name",
  "on_unknown_participant": "REJECT",
  "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",
    "name": "Updated Program Name",
    "on_unknown_participant": "REJECT",
    "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',
    name: 'Updated Program Name',
    on_unknown_participant: 'REJECT',
    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',
    'name' => 'Updated Program Name',
    'on_unknown_participant' => 'REJECT',
    '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  \"name\": \"Updated Program Name\",\n  \"on_unknown_participant\": \"REJECT\",\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  \"name\": \"Updated Program Name\",\n  \"on_unknown_participant\": \"REJECT\",\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  \"name\": \"Updated Program Name\",\n  \"on_unknown_participant\": \"REJECT\",\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",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Q1 Sales Bonus",
  "on_unknown_participant": "CREATE",
  "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": "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

​
id
string<uuid>
required

Program ID

Body

application/json

Fields to update

​
description
string

Program description

Maximum string length: 1000
Example:

"Updated description"

​
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"

​
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"

​
id
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"

​
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"