Participants

Post a CREDIT or DEBIT adjustment to a participant

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

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

Path parameters

participant_idstring required

The participant's id, or ext: followed by the participant's external_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

allow_negativeboolean

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

amountstring required

Adjustment amount (must be positive)

asset_idstring uuid required

Asset to adjust

bucket'AVAILABLE' | 'HELD'

Balance bucket to adjust. Defaults to AVAILABLE

descriptionstring required

Reason for this adjustment

expires_atstring 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_instring

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_keystring

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_atstring 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_instring

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_idstring uuid required

Program this adjustment belongs to

type'CREDIT' | 'DEBIT' required

Whether to credit or debit

Example request

{
  "amount": "100.00",
  "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
  "bucket": "AVAILABLE",
  "description": "Customer service credit",
  "expires_at": "2027-12-31T23:59:59Z",
  "expires_in": "90d",
  "idempotency_key": "adjust-order-123",
  "matures_at": "2027-12-31T23:59:59Z",
  "matures_in": "7d",
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
  "type": "CREDIT"
}

Response

Adjustment applied

amountstring

Amount adjusted

asset_idstring uuid

The asset that was adjusted.

bucket'AVAILABLE' | 'HELD' | 'DEFERRED'

The balance bucket that was adjusted.

journal_entry_idstring uuid

Ledger journal entry created by this adjustment

messagestring

Confirmation message

program_idstring uuid

The program the adjustment belongs to.

type'CREDIT' | 'DEBIT'

Whether the adjustment was a credit or debit

Example response

{
  "amount": "100.00",
  "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
  "balance": {
    "available": "1400.00",
    "deferred": "0.00",
    "held": "200.00"
  },
  "bucket": "AVAILABLE",
  "journal_entry_id": "657a0312-1aaa-4ba7-842b-edfbb39edf14",
  "message": "Balance adjusted successfully",
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
  "type": "CREDIT"
}

Changes

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