--- title: "Create Balance Transaction" method: POST path: "/organizations/{orgId}/balances/{balanceId}/transactions" tags: ["Balances"] --- # Create Balance Transaction `POST /organizations/{orgId}/balances/{balanceId}/transactions` ## Request - Base URL: `https://api.m3ter.com` - URL: `https://api.m3ter.com/organizations/{orgId}/balances/{balanceId}/transactions` - Auth: OAuth 2 - Authorization code: `https://m3ter.auth.us-east-1.amazoncognito.com/oauth2/authorize`, token URL `https://m3ter.auth.us-east-1.amazoncognito.com/oauth2/token` - Client credentials, token URL `/oauth/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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](https://docs.m3ter.com/api/transactiontype/introduction) 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. ## Path parameters - `orgId` string, required - `balanceId` string, required ## Request body - BalanceTransactionRequest - `version` integer: 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. - `description` string: A brief description explaining the purpose and context of the transaction. - `amount` number, required: The financial value of the transaction. - `paid` number: The payment amount if the payment currency differs from the Balance currency. - `currencyPaid` string: The currency code of the payment if it differs from the Balance currency. For example: USD, GBP or EUR. - `transactionTypeId` string: The unique identifier (UUID) of the transaction type. This is obtained from the list of created Transaction Types within the Organization Configuration. - `appliedDate` string, date-time: The date *(in ISO 8601 format)* when the Balance transaction was applied. - `transactionDate` string, date-time: The date *(in ISO 8601 format)* when the transaction occurred. ## Response `200` Returns the created Balance transaction - BalanceTransactionResponse - `id` string, required: The UUID of the entity. - `version` integer: 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. - `description` string: A brief description explaining the purpose or context of the transaction. - `amount` number: The financial value of the transaction, as recorded in the balance. - `paid` number: The actual payment amount if the payment currency differs from the Balance currency. - `currencyPaid` string: 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' - `entityId` string: The unique identifier (UUID) for the entity associated with the Transaction, as specified by the `entityType`. - `transactionTypeId` string: The unique identifier (UUID) for the Transaction type. This is obtained from the list of created Transaction Types within the Organization Configuration. - `appliedDate` string, date-time: The date *(in ISO 8601 format)* when the balance transaction was applied, i.e., when the balance was affected. - `transactionDate` string, date-time: The date *(in ISO 8601 format)* when the transaction was recorded in the system. - `dtCreated` string, date-time: The date and time *(in ISO 8601 format)* when the balance transaction was first created. - `dtLastModified` string, date-time: The date and time *(in ISO 8601 format)* when the balance transaction was last modified. - `createdBy` string: The unique identifier (UUID) for the user who created the balance transaction. - `lastModifiedBy` string: The unique identifier (UUID) for the user who last modified the balance transaction. ## Other responses - `4XX`: Error message - `5XX`: Error message ## Changes - **2026-10-16** `85c514abc692`: 2 breaking - the `allOf[subschema #2]/` request property type changed from no type to `object` - the `allOf[subschema #2]/` response's property type changed from no type to `object` for status `200` - **2025-08-01** `9f9e5f3dbde7`: 1 breaking, 1 warning - the response property `allOf[#/components/schemas/AbstractResponse]/version` became optional for the status `200` - added the new `SCHEDULER` enum value to the `allOf[subschema #2]/entityType` response property for the response status `200` - **2025-02-21** `d064a12d0d93`: 1 breaking, 1 warning - added the pattern `^[a-zA-Z0-9-]*$` to the request property `allOf[subschema #2]/transactionTypeId` - the `allOf[subschema #2]/transactionTypeId` request property's maxLength was set to `36` [Operation history](https://skmtc.dev/m3ter-com/apis/m3ter-api/changes/organizations/:orgId/balances/:balanceId/transactions/post.md) --- [API](https://skmtc.dev/m3ter-com/apis/m3ter-api.md) - [All operations](https://skmtc.dev/m3ter-com/apis/m3ter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/m3ter-com/apis/m3ter-api/revisions/85c514abc692?raw)