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": "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"
}

Balances

Adjust participant balance

Manually credit or debit a participant’s balance. CREDIT adjustments on LOT assets may set expires_at and matures_at as RFC3339 timestamps or positive durations; both durations share one request-time baseline and resolved matures_at must be before expires_at. Future maturity is credited to DEFERRED. Lifecycle fields are rejected for DEBIT, SIMPLE assets, and CREDIT to HELD. Idempotency compares the raw lifecycle strings, and delayed replays return the original journal entry without resolving durations again.

POST

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": "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"
}

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 bound
DEBIT: removes funds. Fails if the participant does not have sufficient available balance, unless allow_negative is true (used for clawbacks)

Every adjustment creates a journal entry in the participant’s transaction history for auditability.

For usage patterns and examples, see the Balance Operations guide.

Authorizations

X-API-Key

string

header

required

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

Headers

Idempotency-Key

string

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: 255

Path Parameters

string<uuid>

required

Participant ID

Body

application/json

Adjustment details

amount

string

required

Adjustment amount (must be positive)

Minimum string length: 1

Example:

"100.00"

asset_id

string<uuid>

required

Asset to adjust

Example:

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

description

string

required

Reason for this adjustment

Required string length: 1 - 500

Example:

"Customer service credit"

program_id

string<uuid>

required

Program this adjustment belongs to

Example:

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

type

enum<string>

required

Whether to credit or debit

Available options:

CREDIT,

DEBIT

Example:

"CREDIT"

allow_negative

boolean

DEBIT only. When true, allows this adjustment to overdraw and set a negative balance.

Example:

false

bucket

enum<string>

Balance bucket to adjust. Defaults to AVAILABLE

Available options:

AVAILABLE,

HELD

Example:

"AVAILABLE"

expires_at

string

CREDIT + LOT only. RFC3339 timestamp or positive duration from request processing time. Not supported with bucket HELD.

Required string length: 1 - 255

Example:

"90d"

idempotency_key

string

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 - 255

Example:

"adjust-order-123"

matures_at

string

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 - 255

Example:

"7d"

Response

Adjustment applied

amount

string

Amount adjusted

Example:

"100.00"

asset_id

string<uuid>

Asset ID

Example:

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

balance

object

Balance after the adjustment

Show child attributes

bucket

string

Balance bucket that was adjusted

Example:

"AVAILABLE"

journal_entry_id

string<uuid>

Ledger journal entry created by this adjustment

Example:

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

message

string

Confirmation message

Example:

"Balance adjusted successfully"

program_id

string<uuid>

Program ID

Example:

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

type

string

Whether the adjustment was a credit or debit

Example:

"CREDIT"

Scrip API

Endpoints

Adjust participant balance

Authorizations

Headers

Path Parameters

Body

Response