--- title: "Update Balance" method: PUT path: "/organizations/{orgId}/balances/{id}" tags: ["Balances"] --- # Update Balance `PUT /organizations/{orgId}/balances/{id}` Update a specific Balance. This endpoint allows you to update the details of a specific Balance. The updated Balance details should be provided in the request body. ## Path parameters - `orgId` string, required - `id` string, required ## Request body - BalanceRequest - `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. - `customFields` object — User defined fields enabling you to attach custom data. The value for a custom field can be either a string or a number. If `customFields` can also be defined for this entity at the Organizational level, `customField` values defined at individual level override values of `customFields` with the same name defined at Organization level. See [Working with Custom Fields](https://www.m3ter.com/docs/guides/creating-and-managing-products/working-with-custom-fields) in the m3ter documentation for more information. - `code` string, required — Unique short code for the Balance. - `name` string, required — The official name for the Balance. - `description` string — A description of the Balance. - `accountId` string, required — The unique identifier (UUID) for the end customer Account. - `startDate` string, date-time, required — The date *(in ISO 8601 format)* when the Balance becomes active. - `endDate` string, date-time, required — The date *(in ISO 8601 format)* after which the Balance will no longer be active for the Account. **Note:** You can use the `rolloverEndDate` request parameter to define an extended grace period for continued draw-down against the Balance if any amount remains when the specified `endDate` is reached. - `currency` string, required — The currency code used for the Balance amount. For example: USD, GBP or EUR. - `rolloverAmount` number — The maximum amount that can be carried over past the Balance end date for draw-down at billing if there is any unused Balance amount when the end date is reached. Works with `rolloverEndDate` to define the amount and duration of a Balance "grace period". *(Optional)* **Notes:** - If you leave `rolloverAmount` empty and only enter a `rolloverEndDate`, any amount left over after the Balance end date is reached will be drawn-down against up to the specified `rolloverEndDate`. - You must enter a `rolloverEndDate`. If you only enter a `rolloverAmount` without entering a `rolloverEndDate`, you'll receive an error when trying to create or update the Balance. - If you don't want to grant any grace period for outstanding Balance amounts, then do not use `rolloverAmount` and `rolloverEndDate`. - `rolloverEndDate` string, date-time — The end date *(in ISO 8601 format)* for the grace period during which unused Balance amounts can be carried over and drawn-down against at billing. **Note:** Use `rolloverAmount` if you want to specify a maximum amount that can be carried over and made available for draw-down. - `balanceDrawDownDescription` string — A description for the bill line items for draw-down charges against the Balance. *(Optional).* - `overageSurchargePercent` number, double — Define a surcharge level, as a percentage of regular usage rating, applied to overages *(usage charges that exceed the Balance amount)*. For example, if the regular usage rate is $10 per unit of usage consumed and `overageSurchargePercent` is set at 10%, then any usage charged above the original Balance amount is charged at $11 per unit of usage. - `overageDescription` string — A description for Bill line items overage charges. - `productIds` string[] — Specify the Products whose consumption charges due at billing can be drawn-down against the Balance amount. **Note:** If you don't specify any Products for Balance draw-down, by default the consumption charges for any Product the Account consumes will be drawn-down against the Balance amount. - `lineItemTypes` BalanceLineItemType[] — Specify the line item charge types that can draw-down at billing against the Balance amount. Options are: - `"MINIMUM_SPEND"` - `"STANDING_CHARGE"` - `"USAGE"` - `"COUNTER_RUNNING_TOTAL_CHARGE"` - `"COUNTER_ADJUSTMENT_DEBIT"` - `AD_HOC` **NOTE:** If no charge types are specified, by default *all types* can draw-down against the Balance amount at billing. - `contractId` string — The unique identifier (UUID) of a Contract on the Account that the Balance will be added to. - `consumptionsAccountingProductId` string — Product ID that any Balance Consumed line items will be attributed to for accounting purposes.(*Optional*) - `feesAccountingProductId` string — Product ID that any Balance Fees line items will be attributed to for accounting purposes.(*Optional*) ## Response `200` Returns the updated Balance - BalanceResponse - `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. - `customFields` object — User defined fields enabling you to attach custom data. The value for a custom field can be either a string or a number. If `customFields` can also be defined for this entity at the Organizational level,`customField` values defined at individual level override values of `customFields` with the same name defined at Organization level. See [Working with Custom Fields](https://www.m3ter.com/docs/guides/creating-and-managing-products/working-with-custom-fields) in the m3ter documentation for more information. - `code` string — A unique short code assigned to the Balance. - `name` string — The official name of the Balance. - `description` string — A description of the Balance. - `accountId` string — The unique identifier (UUID) for the end customer Account the Balance belongs to. - `amount` number — The financial value that the Balance holds. - `currency` string — The currency code used for the Balance amount. For example: USD, GBP or EUR. - `startDate` string, date-time — The date *(in ISO 8601 format)* when the Balance becomes active. - `endDate` string, date-time — The date *(in ISO 8601 format)* after which the Balance will no longer be active. - `rolloverAmount` number — The maximum amount that can be carried over past the Balance end date and draw-down against for billing if there is an unused Balance amount remaining when the Balance end date is reached. - `rolloverEndDate` string, date-time — The end date *(in ISO 8601 format)* for the rollover grace period, which is the period that unused Balance amounts can be carried over beyond the specified Balance `endDate` and continue to be drawn-down against for billing. - `balanceDrawDownDescription` string — A description for the bill line items for charges drawn-down against the Balance. - `overageSurchargePercent` number, double — The percentage surcharge applied to overage charges *(usage above the Balance)*. - `overageDescription` string — A description for overage charges. - `productIds` string[] — A list of Product IDs whose consumption charges due at billing can be drawn-down against the Balance amount. - `lineItemTypes` BalanceLineItemType[] — A list of line item charge types that can draw-down against the Balance amount at billing. - `contractId` string — The unique identifier (UUID) for a Contract on the Account the Balance has been added to. - `consumptionsAccountingProductId` string — Product ID that any Balance Consumed line items will be attributed to for accounting purposes.(*Optional*) - `feesAccountingProductId` string — Product ID that any Balance Fees line items will be attributed to for accounting purposes.(*Optional*) - `dtCreated` string, date-time — The date and time *(in ISO 8601 format)* when the Balance was first created. - `dtLastModified` string, date-time — The date and time *(in ISO 8601 format)* when the Balance was last modified. - `createdBy` string — The unique identifier (UUID) for the user who created the Balance. - `lastModifiedBy` string — The unique identifier (UUID) for the user who last modified the Balance. ## Other responses - `4XX` — Error message - `5XX` — Error message --- [API](https://skmtc.net/m3ter-com/apis/m3ter-api.md) · [All operations](https://skmtc.net/m3ter-com/apis/m3ter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/m3ter-com/m3ter-api/versions/ac93d1a9e6d9/schema)