v10

latestOpenAPI 3.0.1raw.githubusercontent.com2025-12-033223581.2 MB

Balances

Create Balance Transaction

Add a Transaction to a Balance. This endpoint allows you to create a new Transaction amount for a Balance. This amount then becomes available at billing for draw-down to cover charges due. The Transaction details should be provided in the request body.

Before you can add a Transaction amount, you must first set up Transaction Types at the Organization Level - see the Transaction Type section in this API Reference for more details. You can then use this call to add an instance of a Transaction Type to a Balance.

Note: If you have a customer whose payment is in a different currency to the Balance currency, you can use the paid and paidCurrency request parameters to record the amount paid and alternative currency respectively. For example, you might add a Transaction amount of 200 USD to a Balance on a customer Account where the customer actually paid you 50 units in virtual currency X.

post/organizations/{orgId}/balances/{balanceId}/transactions

Path parameters

orgIdstring required

The unique identifier (UUID) for your Organization. The Organization represents your company as a direct customer of our service.

balanceIdstring required

The unique identifier (UUID) for the Balance to which you want to add a transaction.

Request body

versioninteger

The version number of the entity:

Create entity: Not valid for initial insertion of new entity - do not use for Create. On initial Create, version is set at 1 and listed in the response.
Update Entity: On Update, version is required and must match the existing version because a check is performed to ensure sequential versioning is preserved. Version is incremented by 1 and listed in the response.

descriptionstring

A brief description explaining the purpose and context of the transaction.

amountnumber required

The financial value of the transaction.

paidnumber

The payment amount if the payment currency differs from the Balance currency.

currencyPaidstring

The currency code of the payment if it differs from the Balance currency. For example: USD, GBP or EUR.

transactionTypeIdstring

The unique identifier (UUID) of the transaction type. This is obtained from the list of created Transaction Types within the Organization Configuration.

appliedDatestring date-time

The date (in ISO 8601 format) when the Balance transaction was applied.

transactionDatestring date-time

The date (in ISO 8601 format) when the transaction occurred.

Response

Returns the created Balance transaction

idstring required

The UUID of the entity.

versioninteger

The version number:

Create: On initial Create to insert a new entity, the version is set at 1 in the response.
Update: On successful Update, the version is incremented by 1 in the response.

descriptionstring

A brief description explaining the purpose or context of the transaction.

amountnumber

The financial value of the transaction, as recorded in the balance.

paidnumber

The actual payment amount if the payment currency differs from the Balance currency.

currencyPaidstring

The currency code such as USD, GBP, EUR of the payment, if it differs from the balance currency.

entityType'BILL' | 'COMMITMENT' | 'USER' | 'SERVICE_USER' | 'SCHEDULER'

entityIdstring

The unique identifier (UUID) for the entity associated with the Transaction, as specified by the entityType.

transactionTypeIdstring

The unique identifier (UUID) for the Transaction type. This is obtained from the list of created Transaction Types within the Organization Configuration.

appliedDatestring date-time

The date (in ISO 8601 format) when the balance transaction was applied, i.e., when the balance was affected.

transactionDatestring date-time

The date (in ISO 8601 format) when the transaction was recorded in the system.

dtCreatedstring date-time

The date and time (in ISO 8601 format) when the balance transaction was first created.

dtLastModifiedstring date-time

The date and time (in ISO 8601 format) when the balance transaction was last modified.

createdBystring

The unique identifier (UUID) for the user who created the balance transaction.

lastModifiedBystring

The unique identifier (UUID) for the user who last modified the balance transaction.