Adjust group balance

curl --request POST \
  --url https://api.scrip.dev/v1/groups/{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": "Team bonus allocation",
  "program_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "CREDIT",
  "allow_negative": false,
  "bucket": "AVAILABLE",
  "expires_at": "90d",
  "idempotency_key": "adjust-group-123",
  "matures_at": "7d"
}
'

import requests

url = "https://api.scrip.dev/v1/groups/{id}/balances/adjust"

payload = {
    "amount": "100.00",
    "asset_id": "550e8400-e29b-41d4-a716-446655440001",
    "description": "Team bonus allocation",
    "program_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "CREDIT",
    "allow_negative": False,
    "bucket": "AVAILABLE",
    "expires_at": "90d",
    "idempotency_key": "adjust-group-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: 'Team bonus allocation',
    program_id: '550e8400-e29b-41d4-a716-446655440000',
    type: 'CREDIT',
    allow_negative: false,
    bucket: 'AVAILABLE',
    expires_at: '90d',
    idempotency_key: 'adjust-group-123',
    matures_at: '7d'
  })
};

fetch('https://api.scrip.dev/v1/groups/{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/groups/{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' => 'Team bonus allocation',
    'program_id' => '550e8400-e29b-41d4-a716-446655440000',
    'type' => 'CREDIT',
    'allow_negative' => false,
    'bucket' => 'AVAILABLE',
    'expires_at' => '90d',
    'idempotency_key' => 'adjust-group-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/groups/{id}/balances/adjust"

	payload := strings.NewReader("{\n  \"amount\": \"100.00\",\n  \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n  \"description\": \"Team bonus allocation\",\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-group-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/groups/{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\": \"Team bonus allocation\",\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-group-123\",\n  \"matures_at\": \"7d\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.scrip.dev/v1/groups/{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\": \"Team bonus allocation\",\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-group-123\",\n  \"matures_at\": \"7d\"\n}"

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

{
  "amount": "100.00",
  "asset_id": "550e8400-e29b-41d4-a716-446655440001",
  "bucket": "AVAILABLE",
  "journal_entry_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Group 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 group balance

Manually credit or debit a group’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

groups

{id}

balances

adjust

Adjust group balance

curl --request POST \
  --url https://api.scrip.dev/v1/groups/{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": "Team bonus allocation",
  "program_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "CREDIT",
  "allow_negative": false,
  "bucket": "AVAILABLE",
  "expires_at": "90d",
  "idempotency_key": "adjust-group-123",
  "matures_at": "7d"
}
'

import requests

url = "https://api.scrip.dev/v1/groups/{id}/balances/adjust"

payload = {
    "amount": "100.00",
    "asset_id": "550e8400-e29b-41d4-a716-446655440001",
    "description": "Team bonus allocation",
    "program_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "CREDIT",
    "allow_negative": False,
    "bucket": "AVAILABLE",
    "expires_at": "90d",
    "idempotency_key": "adjust-group-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: 'Team bonus allocation',
    program_id: '550e8400-e29b-41d4-a716-446655440000',
    type: 'CREDIT',
    allow_negative: false,
    bucket: 'AVAILABLE',
    expires_at: '90d',
    idempotency_key: 'adjust-group-123',
    matures_at: '7d'
  })
};

fetch('https://api.scrip.dev/v1/groups/{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/groups/{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' => 'Team bonus allocation',
    'program_id' => '550e8400-e29b-41d4-a716-446655440000',
    'type' => 'CREDIT',
    'allow_negative' => false,
    'bucket' => 'AVAILABLE',
    'expires_at' => '90d',
    'idempotency_key' => 'adjust-group-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/groups/{id}/balances/adjust"

	payload := strings.NewReader("{\n  \"amount\": \"100.00\",\n  \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n  \"description\": \"Team bonus allocation\",\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-group-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/groups/{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\": \"Team bonus allocation\",\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-group-123\",\n  \"matures_at\": \"7d\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.scrip.dev/v1/groups/{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\": \"Team bonus allocation\",\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-group-123\",\n  \"matures_at\": \"7d\"\n}"

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

{
  "amount": "100.00",
  "asset_id": "550e8400-e29b-41d4-a716-446655440001",
  "bucket": "AVAILABLE",
  "journal_entry_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Group 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"
}

Credits or debits a group’s balance for a specific asset within a program. Set type to CREDIT or DEBIT and provide a positive amount. A DEBIT fails if the group does not have sufficient balance in the target bucket, unless allow_negative is true (used for clawbacks). The optional bucket field selects AVAILABLE or HELD and defaults to AVAILABLE. You must specify program_id and asset_id to identify which balance to adjust; groups are organization-level entities, but each group maintains separate balances per program-asset pair. The adjustment is atomic and creates a journal entry for auditability. This endpoint mirrors adjust participant balance.

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

Group ID

Body

application/json

Adjustment details

amount

string

required

Adjustment amount (must be positive, decimal string)

Minimum string length: 1

Example:

"100.00"

asset_id

string<uuid>

required

The asset to adjust

Example:

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

description

string

required

Reason for this adjustment (1-500 chars)

Required string length: 1 - 500

Example:

"Team bonus allocation"

program_id

string<uuid>

required

The program this adjustment belongs to

Example:

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

type

enum<string>

required

Whether to CREDIT or DEBIT the balance

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: AVAILABLE or HELD (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-group-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 that was adjusted

Example:

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

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:

"Group balance adjusted successfully"

program_id

string<uuid>

Program the balance belongs to

Example:

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

type

string

Whether the adjustment was a credit or debit

Example:

"CREDIT"

Scrip API

Endpoints

Adjust group balance

Authorizations

Headers

Path Parameters

Body

Response