v1

latestOpenAPI 3.1.02026-07-263644911022.4 KB

Balances API

Create a Balance

Use this endpoint to add new balances to an account.

post/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/balances

Path parameters

organization_idstring uuid required

The unique identifier of the Organization associated with the Ledger.

ledger_idstring uuid required

The unique identifier of the associated Ledger.

account_idstring uuid required

The unique identifier of the account.

Headers

Content-Typestring

The type of media of the resource. Recommended value is application/json.

X-Request-Idstring uuid

A unique identifier used to trace and track each request.

Authorizationstring

Bearer JWT token for authentication. Required when PLUGIN_AUTH_ENABLED=true (enforced in multi-tenant deployments). Optional in default OSS single-tenant mode. Format: Bearer <token>

Request body

keystring required

The unique identifier for the balance in the context of the account. Must not contain whitespace. The value "overdraft" is reserved for system-managed companion balances and cannot be used here.

allowSendingboolean

If true, indicates that the balance can be used to send transactions.

allowReceivingboolean

If true, indicates that the balance can be used to receive transactions.

direction'credit' | 'debit'

The accounting direction of the balance. credit (default) for balances that grow on credit; debit for balances that grow on debit. Set at creation and immutable.

Response

Indicates that the request was successful and the response contains the expected data.

idstring

The unique identifier of the Balance.

organizationIdstring uuid

The unique identifier of the Organization.

ledgerIdstring uuid

The unique identifier of the Ledger.

accountIdstring uuid

The unique identifier of the Account.

aliasstring

The alias for the account used in the operation.

keystring

The unique identifier for the balance in the context of the account.

assetCodestring

The name of the asset used in the operation.

availablestring

Previous available balance.

onHoldstring

Amount on hold/reserved.

versioninteger

Balance version, which is updated with each transaction.

accountTypestring

The type of account.

allowSendingboolean

If true, indicates that the balance can be used to send transactions.

allowReceivingboolean

If true, indicates that the balance can be used to receive transactions.

direction'credit' | 'debit'

The accounting direction of the balance. credit balances grow on credit and shrink on debit; debit balances grow on debit and shrink on credit. Set at creation and immutable.

overdraftUsedstring

The amount of overdraft currently consumed by this balance, as a decimal string. Always non-negative; "0" when the balance has no overdraft active.

createdAtstring date-time

Timestamp of creation (UTC).

updatedAtstring date-time

Timestamp of last update (UTC).

deletedAtstring date-time nullable

Timestamp of soft deletion, if applicable (UTC).

metadataMetadata

An object containing key-value pairs to add as metadata, where the field name is the key and the field value is the value. For example, to add a Cost Center, use 'costCenter': 'BR_11101997'.

Constraints: keys must be at most 100 characters; string values at most 2000 characters. Nested objects are not allowed (values must be string, number, or boolean), the structure may not exceed a maximum depth of 10, and a maximum of 100 keys is permitted.