Adjust participant balance
curl --request POST \
--url https://api.scrip.dev/v1/participants/{id}/balances/adjust \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"amount": "100.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440001",
"description": "Customer service credit",
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CREDIT",
"allow_negative": false,
"bucket": "AVAILABLE",
"expires_at": "90d",
"idempotency_key": "adjust-order-123",
"matures_at": "7d"
}
'import requests
url = "https://api.scrip.dev/v1/participants/{id}/balances/adjust"
payload = {
"amount": "100.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440001",
"description": "Customer service credit",
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CREDIT",
"allow_negative": False,
"bucket": "AVAILABLE",
"expires_at": "90d",
"idempotency_key": "adjust-order-123",
"matures_at": "7d"
}
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({
amount: '100.00',
asset_id: '550e8400-e29b-41d4-a716-446655440001',
description: 'Customer service credit',
program_id: '550e8400-e29b-41d4-a716-446655440000',
type: 'CREDIT',
allow_negative: false,
bucket: 'AVAILABLE',
expires_at: '90d',
idempotency_key: 'adjust-order-123',
matures_at: '7d'
})
};
fetch('https://api.scrip.dev/v1/participants/{id}/balances/adjust', 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}/balances/adjust",
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([
'amount' => '100.00',
'asset_id' => '550e8400-e29b-41d4-a716-446655440001',
'description' => 'Customer service credit',
'program_id' => '550e8400-e29b-41d4-a716-446655440000',
'type' => 'CREDIT',
'allow_negative' => false,
'bucket' => 'AVAILABLE',
'expires_at' => '90d',
'idempotency_key' => 'adjust-order-123',
'matures_at' => '7d'
]),
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}/balances/adjust"
payload := strings.NewReader("{\n \"amount\": \"100.00\",\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"description\": \"Customer service credit\",\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"type\": \"CREDIT\",\n \"allow_negative\": false,\n \"bucket\": \"AVAILABLE\",\n \"expires_at\": \"90d\",\n \"idempotency_key\": \"adjust-order-123\",\n \"matures_at\": \"7d\"\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}/balances/adjust")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"100.00\",\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"description\": \"Customer service credit\",\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"type\": \"CREDIT\",\n \"allow_negative\": false,\n \"bucket\": \"AVAILABLE\",\n \"expires_at\": \"90d\",\n \"idempotency_key\": \"adjust-order-123\",\n \"matures_at\": \"7d\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scrip.dev/v1/participants/{id}/balances/adjust")
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 \"amount\": \"100.00\",\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"description\": \"Customer service credit\",\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"type\": \"CREDIT\",\n \"allow_negative\": false,\n \"bucket\": \"AVAILABLE\",\n \"expires_at\": \"90d\",\n \"idempotency_key\": \"adjust-order-123\",\n \"matures_at\": \"7d\"\n}"
response = http.request(request)
puts response.read_body{
"amount": "100.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440001",
"balance": {
"available": "1400.00",
"deferred": "0.00",
"held": "200.00"
},
"bucket": "AVAILABLE",
"journal_entry_id": "550e8400-e29b-41d4-a716-446655440000",
"message": "Balance adjusted successfully",
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CREDIT"
}{
"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": "forbidden",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Insufficient permissions for this action"
}{
"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"
}Balances
Adjust participant balance
Manually credit or debit a participant’s balance.
POST
/
v1
/
participants
/
{id}
/
balances
/
adjust
Adjust participant balance
curl --request POST \
--url https://api.scrip.dev/v1/participants/{id}/balances/adjust \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"amount": "100.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440001",
"description": "Customer service credit",
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CREDIT",
"allow_negative": false,
"bucket": "AVAILABLE",
"expires_at": "90d",
"idempotency_key": "adjust-order-123",
"matures_at": "7d"
}
'import requests
url = "https://api.scrip.dev/v1/participants/{id}/balances/adjust"
payload = {
"amount": "100.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440001",
"description": "Customer service credit",
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CREDIT",
"allow_negative": False,
"bucket": "AVAILABLE",
"expires_at": "90d",
"idempotency_key": "adjust-order-123",
"matures_at": "7d"
}
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({
amount: '100.00',
asset_id: '550e8400-e29b-41d4-a716-446655440001',
description: 'Customer service credit',
program_id: '550e8400-e29b-41d4-a716-446655440000',
type: 'CREDIT',
allow_negative: false,
bucket: 'AVAILABLE',
expires_at: '90d',
idempotency_key: 'adjust-order-123',
matures_at: '7d'
})
};
fetch('https://api.scrip.dev/v1/participants/{id}/balances/adjust', 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}/balances/adjust",
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([
'amount' => '100.00',
'asset_id' => '550e8400-e29b-41d4-a716-446655440001',
'description' => 'Customer service credit',
'program_id' => '550e8400-e29b-41d4-a716-446655440000',
'type' => 'CREDIT',
'allow_negative' => false,
'bucket' => 'AVAILABLE',
'expires_at' => '90d',
'idempotency_key' => 'adjust-order-123',
'matures_at' => '7d'
]),
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}/balances/adjust"
payload := strings.NewReader("{\n \"amount\": \"100.00\",\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"description\": \"Customer service credit\",\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"type\": \"CREDIT\",\n \"allow_negative\": false,\n \"bucket\": \"AVAILABLE\",\n \"expires_at\": \"90d\",\n \"idempotency_key\": \"adjust-order-123\",\n \"matures_at\": \"7d\"\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}/balances/adjust")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"100.00\",\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"description\": \"Customer service credit\",\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"type\": \"CREDIT\",\n \"allow_negative\": false,\n \"bucket\": \"AVAILABLE\",\n \"expires_at\": \"90d\",\n \"idempotency_key\": \"adjust-order-123\",\n \"matures_at\": \"7d\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scrip.dev/v1/participants/{id}/balances/adjust")
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 \"amount\": \"100.00\",\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"description\": \"Customer service credit\",\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"type\": \"CREDIT\",\n \"allow_negative\": false,\n \"bucket\": \"AVAILABLE\",\n \"expires_at\": \"90d\",\n \"idempotency_key\": \"adjust-order-123\",\n \"matures_at\": \"7d\"\n}"
response = http.request(request)
puts response.read_body{
"amount": "100.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440001",
"balance": {
"available": "1400.00",
"deferred": "0.00",
"held": "200.00"
},
"bucket": "AVAILABLE",
"journal_entry_id": "550e8400-e29b-41d4-a716-446655440000",
"message": "Balance adjusted successfully",
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CREDIT"
}{
"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": "forbidden",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Insufficient permissions for this action"
}{
"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"
}Manually credit or debit a participant’s balance. Intended for customer service corrections, manual workflows, and one-off adjustments outside of the rules engine.
CREDIT: adds funds. No upper boundDEBIT: removes funds. Fails if the participant does not have sufficientavailablebalance, unlessallow_negativeistrue(used for clawbacks)
action_type is CREDIT or DEBIT, matching type; there is no separate adjustment action type. To find manual adjustments in journal entries, statements, or transaction history, look for CREDIT and DEBIT entries whose event_id and rule_id are both null. Entries created by rules carry both IDs.
For usage patterns and examples, see the Balance Operations guide, including expiration and maturity on credits.
Authorizations
ApiKeyAuthBearerAuth
API key passed in the X-API-Key header.
Headers
Idempotency key (1-255 printable ASCII chars). Equivalent to the idempotency_key body field; if both are provided they must match. Replays with the same key and identical parameters return the original journal_entry_id; the same key with different parameters returns 409 idempotency_conflict.
Maximum string length:
255Path Parameters
Participant ID
Body
application/json
Adjustment details
Adjustment amount (must be positive)
Minimum string length:
1Example:
"100.00"
Asset to adjust
Example:
"550e8400-e29b-41d4-a716-446655440001"
Reason for this adjustment
Required string length:
1 - 500Example:
"Customer service credit"
Program this adjustment belongs to
Example:
"550e8400-e29b-41d4-a716-446655440000"
Whether to credit or debit
Available options:
CREDIT, DEBIT Example:
"CREDIT"
DEBIT only. When true, allows this adjustment to overdraw and set a negative balance.
Example:
false
Balance bucket to adjust. Defaults to AVAILABLE
Available options:
AVAILABLE, HELD Example:
"AVAILABLE"
CREDIT + LOT only. RFC3339 timestamp or positive duration from request processing time. Not supported with bucket HELD.
Required string length:
1 - 255Example:
"90d"
Client-provided key to dedupe retries. May also be supplied via the Idempotency-Key HTTP header; when both are present they must match. Identical adjusts with the same key return the original journal_entry_id; a reused key with different payload returns 409 idempotency_conflict.
Required string length:
1 - 255Example:
"adjust-order-123"
CREDIT + LOT only. RFC3339 timestamp or positive duration from request processing time. Future values route the credit to DEFERRED. Not supported with bucket HELD.
Required string length:
1 - 255Example:
"7d"
Response
Adjustment applied
Amount adjusted
Example:
"100.00"
Asset ID
Example:
"550e8400-e29b-41d4-a716-446655440001"
Balance after the adjustment
Show child attributes
Show child attributes
Balance bucket that was adjusted
Example:
"AVAILABLE"
Ledger journal entry created by this adjustment
Example:
"550e8400-e29b-41d4-a716-446655440000"
Confirmation message
Example:
"Balance adjusted successfully"
Program ID
Example:
"550e8400-e29b-41d4-a716-446655440000"
Whether the adjustment was a credit or debit
Example:
"CREDIT"