---
title: "Post a CREDIT or DEBIT adjustment to a participant"
method: POST
path: "/v1/participants/{participant_id}/balances/adjust"
tags: ["Participants"]
---

# Post a CREDIT or DEBIT adjustment to a participant

`POST /v1/participants/{participant_id}/balances/adjust`

## Request

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

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

## Path parameters

- `participant_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- AdjustBalanceRequest: Credits or debits a participant'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)
  - `asset_id` string, uuid, required: Asset to adjust
  - `bucket` 'AVAILABLE' | 'HELD': Balance bucket to adjust. Defaults to AVAILABLE
  - `description` string, required: Reason for this adjustment
  - `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: Program this adjustment belongs to
  - `type` 'CREDIT' | 'DEBIT', required: Whether to credit or debit

## Response `200`

Adjustment applied

- AdjustBalanceResponse: The result of a participant balance adjustment: the journal entry that recorded it and the balance after it.
  - `amount` string: Amount adjusted
  - `asset_id` string, uuid: The asset that was adjusted.
  - `balance` BalanceSummary: A balance split into available, held and deferred amounts.
    - `available` string: Spendable balance
    - `deferred` string: Balance not yet matured
    - `held` string: Balance reserved by hold operations
  - `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: The program the adjustment belongs to.
  - `type` 'CREDIT' | 'DEBIT': Whether the adjustment was a credit or debit

## Other responses

- `400`: Validation failed, amount must be positive and non-zero, 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`: Participant, program, or asset not found (code: participant_not_found | program_not_found | asset_not_found)
- `409`: Participant inactive, idempotency key reused with a different payload, or another request changed the same balance at the same time (code: participant_inactive | idempotency_conflict | retryable_conflict | program_inactive)
- `422`: Insufficient funds, archived asset, or invalid amount (code: insufficient_funds | asset_archived | invalid_amount | amount_exceeds_maximum | 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)