Groups

Forfeit group balance

Moves group balance to breakage (system account). Allowed on archived assets as an explicit cleanup operation.

post/v1/groups/{group_id}/balances/forfeit

Request

  • Base URL: https://api.scrip.dev
  • URL: https://api.scrip.dev/v1/groups/{group_id}/balances/forfeit
  • Auth: HTTP bearer

Path parameters

group_idstring uuid required

The group's id.

Headers

Idempotency-Keystring

A key you choose to make this request safe to retry: 1 to 255 printable ASCII characters. Send the same key with the same request to get the first response again, marked Idempotent-Replayed: true. Routes that return a secret once, and claim links, do not replay a response. Event ingest uses the key as the event's identity.

Request body

amountstring

Amount to process. Omit to process the full balance (SIMPLE) or all matching lots (LOT)

asset_idstring uuid required

Asset to operate on

bucket'AVAILABLE' | 'HELD'

Which bucket to forfeit from. Required for forfeit; ignored for hold/release

descriptionstring required

Reason for this operation

earned_fromstring date-time

Only process lots earned on or after this time (RFC 3339). LOT mode only. Void pending rejects this field.

earned_tostring date-time

Only process lots earned on or before this time (RFC 3339). LOT mode only. Must be >= earned_from when both are provided. Void pending rejects this field.

idempotency_keystring

Your key for this operation. 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.

lot_idsstring[]

Restrict to specific lots. LOT mode only. Void pending rejects this field.

program_idstring uuid required

Program this operation belongs to

reference_idstring

Correlation ID that links a hold to its release, or names the pending rewards to void. It cannot start with scrip:. LOT mode only. Required for void pending; forfeit rejects it.

Example request

{
  "amount": "100.00",
  "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
  "bucket": "AVAILABLE",
  "description": "Order #123",
  "earned_from": "2027-01-01T00:00:00Z",
  "earned_to": "2027-12-31T23:59:59Z",
  "idempotency_key": "order-1001-completed",
  "lot_ids": [
    "4a6c8e02-b1d3-4f57-9c80-e2a4b6d8f012"
  ],
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
  "reference_id": "auth_12345"
}

Response

Balance forfeited

amount_processedstring

Total amount processed

asset_idstring uuid

The asset the operation applied to.

journal_entry_idstring uuid

Ledger journal entry created by this operation

messagestring

Confirmation message

operation'HOLD' | 'RELEASE' | 'FORFEIT' | 'VOID_PENDING'

The balance operation that was performed, matching the endpoint you called.

program_idstring uuid

The program the operation belongs to.

reference_idstring

Correlation ID linking this hold/release (if provided)

Example response

{
  "amount_processed": "100.00",
  "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
  "balance": {
    "available": "1400.00",
    "deferred": "0.00",
    "held": "200.00"
  },
  "journal_entry_id": "657a0312-1aaa-4ba7-842b-edfbb39edf14",
  "lots_processed": [
    {
      "amount": "50.00",
      "id": "4a6c8e02-b1d3-4f57-9c80-e2a4b6d8f012"
    }
  ],
  "message": "Processed 100.00",
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
  "reference_id": "auth_12345"
}

Changes

No recorded changes to this operation across all 1 revision of this API.