Create Balance

Authorizations

Authorization

string

header

required

m3ter supports machine to machine authentication using the clientCredentials OAuth2 flow.

The authorizationCode flow controls access for human users via the m3ter Console application.

Path Parameters

orgId

string

required

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

Body

application/json

code

string

required

Unique short code for the Balance.

Required string length: 1 - 80

name

string

required

The official name for the Balance.

Minimum string length: 1

accountId

string

required

The unique identifier (UUID) for the end customer Account.

Minimum string length: 1

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.

Minimum string length: 1

version

integer<int64>

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

any

description

string

A description of the Balance.

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.

Required range: x >= 0

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).

Maximum string length: 200

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.

Maximum string length: 200

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

enum<string>[]

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.

Available line item types for Balances

Available options:

STANDING_CHARGE,

USAGE,

MINIMUM_SPEND,

COUNTER_RUNNING_TOTAL_CHARGE,

COUNTER_ADJUSTMENT_DEBIT,

AD_HOC

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)

Required string length: 36

feesAccountingProductId

string

Product ID that any Balance Fees line items will be attributed to for accounting purposes.(Optional)

Required string length: 36

allowOverdraft

boolean

Allow balance amounts to fall below zero. This feature is enabled on request. Please get in touch with m3ter Support or your m3ter contact if you would like it enabling for your organization(s).

Example:

false

Response

Returns the created Balance

string

required

The UUID of the entity.

version

integer<int64>

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

enum<string>[]

A list of line item charge types that can draw-down against the Balance amount at billing.

Available line item types for Balances

Available options:

STANDING_CHARGE,

USAGE,

MINIMUM_SPEND,

COUNTER_RUNNING_TOTAL_CHARGE,

COUNTER_ADJUSTMENT_DEBIT,

AD_HOC

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)

allowOverdraft

boolean

Allow balance amounts to fall below zero. This feature is enabled on request. Please get in touch with m3ter Support or your m3ter contact if you would like it enabling for your organization(s).

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.

Getting Started

Endpoints

Authorizations

Path Parameters

Body

Response