---
title: "Post a CREDIT or DEBIT adjustment to a group"
method: POST
path: "/v1/groups/{group_id}/balances/adjust"
tags: ["Groups"]
---

# Post a CREDIT or DEBIT adjustment to a group

`POST /v1/groups/{group_id}/balances/adjust`

## Request

- Base URL: `https://api.scrip.dev`
- URL: `https://api.scrip.dev/v1/groups/{group_id}/balances/adjust`
- Auth: HTTP bearer

Post a CREDIT or DEBIT journal entry that manually adds to or removes from a group's balance.

## Path parameters

- `group_id` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- AdjustGroupBalanceRequest: Credits or debits a group's balance in one asset. `type` chooses which, and `amount` is always positive.
  - `allow_negative` boolean: DEBIT only. When true, allows this adjustment to overdraw and set a negative balance.
  - `amount` string, required: Adjustment amount (must be positive, decimal string)
  - `asset_id` string, uuid, required: The asset to adjust
  - `bucket` 'AVAILABLE' | 'HELD': Balance bucket to adjust: AVAILABLE or HELD (defaults to AVAILABLE)
  - `description` string, required: Reason for this adjustment (1-500 chars)
  - `expires_at` string, date-time: CREDIT + LOT only. When the credited lot expires, as an RFC 3339 timestamp. To expire after a duration, send expires_in. Send one of the two, not both. Not supported with bucket HELD.
  - `expires_in` string: CREDIT + LOT only. How long after this request the credited lot expires, as a duration such as "90d". Units are w, d, h, m and s. Send expires_in or expires_at, not both. Not supported with bucket HELD.
  - `idempotency_key` string: Your key for this adjustment. You can send it in the Idempotency-Key header instead; when both are sent they must match. The same key with the same fields returns the first result again, and the same key with different fields returns 409 `idempotency_conflict`.
  - `matures_at` string, date-time: CREDIT + LOT only. When the credited lot becomes spendable, as an RFC 3339 timestamp. A future value routes the credit to DEFERRED. To mature after a duration, send matures_in. Send one of the two, not both. Not supported with bucket HELD.
  - `matures_in` string: CREDIT + LOT only. How long after this request the credited lot becomes spendable, as a duration such as "7d". Units are w, d, h, m and s. A future value routes the credit to DEFERRED. Send matures_in or matures_at, not both. Not supported with bucket HELD.
  - `program_id` string, uuid, required: The program this adjustment belongs to
  - `type` 'CREDIT' | 'DEBIT', required: Whether to CREDIT or DEBIT the balance

## Response `200`

Adjustment applied

- GroupAdjustBalanceResponse: The result of a group balance adjustment: the journal entry that recorded it.
  - `amount` string: Amount adjusted
  - `asset_id` string, uuid: Asset that was adjusted
  - `bucket` 'AVAILABLE' | 'HELD' | 'DEFERRED': The balance bucket that was adjusted.
  - `journal_entry_id` string, uuid: Ledger journal entry created by this adjustment
  - `message` string: Confirmation message
  - `program_id` string, uuid: Program the balance belongs to
  - `type` 'CREDIT' | 'DEBIT': Whether the adjustment was a credit or debit

## Other responses

- `400`: Validation failed, lifecycle metadata is invalid/unsupported, or invalid/mismatched Idempotency-Key header (code: validation_error | header_body_mismatch | invalid_lot_lifecycle | invalid_lot_lifecycle_order)
- `401`: The API key is missing or not valid. See [Authentication](https://docs.scrip.dev/authentication).
- `403`: The caller is not allowed to do this.
- `404`: Resource not found (code: group_not_found | program_not_found | asset_not_found)
- `409`: Idempotency key reused with a different payload, or another request changed the same balance at the same time (code: idempotency_conflict | retryable_conflict | program_inactive)
- `422`: Insufficient funds, archived asset, or invalid amount (code: insufficient_funds | asset_archived | invalid_inventory_mode)
- `429`: Too many requests. Wait the number of seconds in the `Retry-After` header, then retry. See [Limits and durations](https://docs.scrip.dev/limits#rate-limits).
- `500`: Something failed on Scrip's side. Retry the request, and quote `request_id` if it keeps failing. [Errors](https://docs.scrip.dev/errors) lists every code, and the [API introduction](https://docs.scrip.dev/api-reference/introduction) describes the error format.

---

[API](https://skmtc.dev/scrip/apis/scrip-api.md) · [All operations](https://skmtc.dev/scrip/apis/scrip-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scrip/apis/scrip-api/revisions/c52d35da8d97?raw)