Create Commitment

curl --request POST \
  --url https://api.m3ter.com/organizations/{orgId}/commitments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "<string>",
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "currency": "<string>",
  "amount": 1,
  "version": 123,
  "billingPlanId": "<string>",
  "productIds": [
    "<string>"
  ],
  "amountPrePaid": 1,
  "amountFirstBill": 1,
  "overageSurchargePercent": 123,
  "separateOverageUsage": true,
  "billingInterval": 183,
  "billingOffset": 182,
  "commitmentFeeDescription": "<string>",
  "commitmentUsageDescription": "<string>",
  "overageDescription": "<string>",
  "commitmentFeeBillInAdvance": true,
  "billEpoch": "2023-12-25",
  "contractId": "<string>",
  "accountingProductId": "<string>",
  "feesAccountingProductId": "<string>",
  "drawdownsAccountingProductId": "<string>",
  "feeDates": [
    {
      "date": "2023-12-25",
      "amount": 1,
      "servicePeriodStartDate": "2023-11-07T05:31:56Z",
      "servicePeriodEndDate": "2023-11-07T05:31:56Z"
    }
  ],
  "childBillingMode": "<unknown>",
  "lineItemTypes": []
}
'

{
  "id": "<string>",
  "version": 123,
  "accountId": "<string>",
  "billingPlanId": "<string>",
  "productIds": [
    "<string>"
  ],
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "currency": "<string>",
  "amount": 123,
  "amountPrePaid": 123,
  "amountFirstBill": 123,
  "amountSpent": 123,
  "overageSurchargePercent": 123,
  "separateOverageUsage": true,
  "billingInterval": 123,
  "billingOffset": 123,
  "commitmentFeeDescription": "<string>",
  "commitmentUsageDescription": "<string>",
  "overageDescription": "<string>",
  "commitmentFeeBillInAdvance": true,
  "billEpoch": "2023-12-25",
  "contractId": "<string>",
  "accountingProductId": "<string>",
  "feesAccountingProductId": "<string>",
  "drawdownsAccountingProductId": "<string>",
  "feeDates": [
    {
      "date": "2023-12-25",
      "amount": 1,
      "servicePeriodStartDate": "2023-11-07T05:31:56Z",
      "servicePeriodEndDate": "2023-11-07T05:31:56Z"
    }
  ],
  "lineItemTypes": [],
  "dtCreated": "2023-11-07T05:31:56Z",
  "dtLastModified": "2023-11-07T05:31:56Z",
  "createdBy": "<string>",
  "lastModifiedBy": "<string>"
}

Create Commitment

Create a new Commitment.

Creates a new Commitment for an Organization. The request body must include all the necessary details such as the agreed amount, overage surcharge percentage, and the associated account and product details.

Note: If some of the agreed Commitment amount remains unpaid at the start of an end-customer contract period, when you create a Commitment for an Account you can set up billing for the outstanding amount in one of two ways:

Select a Product Plan to bill with. Use the billingPlanId request parameter to select the Plan used for billing.
Define a schedule of billing dates. Omit a billingPlanId and use the feeDates request parameter to define a precise schedule of bill dates and amounts.

POST

organizations

{orgId}

commitments

Create Commitment

curl --request POST \
  --url https://api.m3ter.com/organizations/{orgId}/commitments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "<string>",
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "currency": "<string>",
  "amount": 1,
  "version": 123,
  "billingPlanId": "<string>",
  "productIds": [
    "<string>"
  ],
  "amountPrePaid": 1,
  "amountFirstBill": 1,
  "overageSurchargePercent": 123,
  "separateOverageUsage": true,
  "billingInterval": 183,
  "billingOffset": 182,
  "commitmentFeeDescription": "<string>",
  "commitmentUsageDescription": "<string>",
  "overageDescription": "<string>",
  "commitmentFeeBillInAdvance": true,
  "billEpoch": "2023-12-25",
  "contractId": "<string>",
  "accountingProductId": "<string>",
  "feesAccountingProductId": "<string>",
  "drawdownsAccountingProductId": "<string>",
  "feeDates": [
    {
      "date": "2023-12-25",
      "amount": 1,
      "servicePeriodStartDate": "2023-11-07T05:31:56Z",
      "servicePeriodEndDate": "2023-11-07T05:31:56Z"
    }
  ],
  "childBillingMode": "<unknown>",
  "lineItemTypes": []
}
'

{
  "id": "<string>",
  "version": 123,
  "accountId": "<string>",
  "billingPlanId": "<string>",
  "productIds": [
    "<string>"
  ],
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "currency": "<string>",
  "amount": 123,
  "amountPrePaid": 123,
  "amountFirstBill": 123,
  "amountSpent": 123,
  "overageSurchargePercent": 123,
  "separateOverageUsage": true,
  "billingInterval": 123,
  "billingOffset": 123,
  "commitmentFeeDescription": "<string>",
  "commitmentUsageDescription": "<string>",
  "overageDescription": "<string>",
  "commitmentFeeBillInAdvance": true,
  "billEpoch": "2023-12-25",
  "contractId": "<string>",
  "accountingProductId": "<string>",
  "feesAccountingProductId": "<string>",
  "drawdownsAccountingProductId": "<string>",
  "feeDates": [
    {
      "date": "2023-12-25",
      "amount": 1,
      "servicePeriodStartDate": "2023-11-07T05:31:56Z",
      "servicePeriodEndDate": "2023-11-07T05:31:56Z"
    }
  ],
  "lineItemTypes": [],
  "dtCreated": "2023-11-07T05:31:56Z",
  "dtLastModified": "2023-11-07T05:31:56Z",
  "createdBy": "<string>",
  "lastModifiedBy": "<string>"
}

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. This represents your company as a direct customer of our service.

Body

application/json

accountId

string

required

The unique identifier (UUID) for the end customer Account the Commitment is added to.

Required string length: 36

startDate

string<date>

required

The start date of the Commitment period in ISO-8601 format.

endDate

string<date>

required

The end date of the Commitment period in ISO-8601 format.

Note: End date is exclusive - if you set an end date of June 1st 2022, then the Commitment ceases to be active for the Account at midnight on May 31st 2022, and any Prepayment fees due are calculated up to that point in time, NOT up to midnight on June 1st

currency

string

required

The currency used for the Commitment. For example: USD.

Minimum string length: 1

amount

number<double>

required

The total amount that the customer has committed to pay.

Required range: x > 0

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.

billingPlanId

string

The unique identifier (UUID) for the Product Plan used for billing Commitment fees due.

Maximum string length: 36

productIds

string[]

A list of unique identifiers (UUIDs) for Products the Account consumes. Charges due for these Products will be made available for draw-down against the Commitment.

Note: If not used, then charges due for all Products the Account consumes will be made available for draw-down against the Commitment.

Maximum array length: 100

amountPrePaid

number<double>

The amount that the customer has already paid upfront at the start of the Commitment service period.

Required range: x >= 0

amountFirstBill

number<double>

The amount to be billed in the first invoice.

Required range: x >= 0

overageSurchargePercent

number<double>

The percentage surcharge applied to usage charges that exceed the Commitment amount.

Note: You can enter a negative percentage if you want to give a discount rate for usage to end customers who exceed their Commitment amount

separateOverageUsage

boolean

A boolean value indicating whether the overage usage is billed separately or together. If overage usage is separated and a Commitment amount has been consumed by an Account, any subsequent line items on Bills against the Account for usage will show as separate "overage usage" charges, not simply as "usage" charges:

TRUE - billed separately.
FALSE - billed together.

Notes:

Can be used only if no value or 0 has been defined for the overageSurchargePercent parameter. If you try to separate overage usage when a value other than 0 has been defined for overageSurchargePercent, you'll receive an error.
If a priced Plan is used to bill any outstanding Commitment fees due and the Plan is set up with overage pricing on a tiered pricing structure and you enable separate bill line items for overage usage, then overage usage charges will be rated according to the overage pricing defined for the tiered pricing on the Plan.

billingInterval

integer<int32>

How often the Commitment fees are applied to bills. For example, if the plan being used to bill for Commitment fees is set to issue bills every three months and the billingInterval is set to 2, then the Commitment fees are applied every six months.

Required range: 1 <= x <= 365

billingOffset

integer<int32>

Defines an offset for when the Commitment fees are first applied to bills on the Account. For example, if bills are issued every three months and the billingOffset is 0, then the charge is applied to the first bill (at three months); if set to 1, it's applied to the next bill (at six months), and so on.

Required range: 0 <= x <= 364

commitmentFeeDescription

string

A textual description of the Commitment fee.

Maximum string length: 200

commitmentUsageDescription

string

A textual description of the Commitment usage.

Maximum string length: 200

overageDescription

string

A textual description of the overage charges.

Maximum string length: 200

commitmentFeeBillInAdvance

boolean

A boolean value indicating whether the Commitment fee is billed in advance (start of each billing period) or arrears (end of each billing period).

If no value is supplied, then the Organization Configuration value is used.

TRUE - bill in advance (start of each billing period).
FALSE - bill in arrears (end of each billing period).

billEpoch

string<date>

The starting date (in ISO-8601 date format) from which the billing cycles are calculated.

contractId

string

The unique identifier (UUID) for a Contract you've created for the Account - used to add the Commitment to this Contract.

Note: If you associate the Commitment with a Contract you must ensure the Account Plan attached to the Account has the same Contract associated with it. If the Account Plan Contract and Commitment Contract do not match, then at billing the Commitment amount will not be drawn-down against.

Required string length: 36

accountingProductId

string

The unique identifier (UUID) for the Product linked to the Commitment for accounting purposes. (Optional)

NOTE: If you're planning to set up an integration for sending Bills to an external accounts receivable system, please check requirements for your chosen system. Some systems, such as NetSuite, require a Product to be linked with any Bill line items associated with Account Commitments, and the integration will fail if this is not present

Required string length: 36

feesAccountingProductId

string

Optional Product ID this Commitment's fees should be attributed to for accounting purposes.

Required string length: 36

drawdownsAccountingProductId

string

Optional Product ID this Commitment's consumptions should be attributed to for accounting purposes.

Required string length: 36

feeDates

object[]

Used for billing any outstanding Commitment fees on a schedule.

Create an array to define a series of bill dates and amounts covering specified service periods:

date - the billing date (in ISO-8601 format).
amount - the billed amount.
servicePeriodStartDate and servicePeriodEndDate - defines the service period the bill covers (in ISO-8601 format).

Notes:

If you try to set servicePeriodStartDate after servicePeriodEndDate, you'll receive an error.
You can set servicePeriodStartDate and servicePeriodEndDate to the same date without receiving an error, but please be sure your Commitment billing use case requires this.

Show child attributes

childBillingMode

any

lineItemTypes

enum<string>[]

Specify the line item charge types that can draw-down at billing against the Commitment amount. Options are:

MINIMUM_SPEND
STANDING_CHARGE
USAGE
"COUNTER_RUNNING_TOTAL_CHARGE"
"COUNTER_ADJUSTMENT_DEBIT"

NOTE: If no charge types are specified, by default all types can draw-down against the Commitment amount at billing.

Available line item types for Commitments

Available options:

STANDING_CHARGE,

USAGE,

MINIMUM_SPEND,

COUNTER_RUNNING_TOTAL_CHARGE,

COUNTER_ADJUSTMENT_DEBIT

Response

Returns the created Commitment

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.

accountId

string

The unique identifier (UUID) for the end customer Account the Commitment is added to.

billingPlanId

string

The unique identifier (UUID) for the Product Plan used for billing Commitment fees due.

productIds

string[]

A list of unique identifiers (UUIDs) for Products the Account consumes. Charges due for these Products will be made available for draw-down against the Commitment.

Note: If not used, then charges due for all Products the Account consumes will be made available for draw-down against the Commitment.

startDate

string<date>

The start date of the Commitment period in ISO-8601 format.

endDate

string<date>

The end date of the Commitment period in ISO-8601 format.

currency

string

The currency used for the Commitment. For example, 'USD'.

amount

number<double>

The total amount that the customer has committed to pay.

amountPrePaid

number<double>

The amount that the customer has already paid upfront at the start of the Commitment service period.

amountFirstBill

number<double>

The amount to be billed in the first invoice.

amountSpent

number<double>

The total amount of the Commitment that the customer has spent so far.

overageSurchargePercent

number<double>

The percentage surcharge applied to the usage charges that exceed the Commitment amount.

separateOverageUsage

boolean

TRUE - billed separately.
FALSE - billed together.

billingInterval

integer<int32>

billingOffset

integer<int32>

The offset for when the Commitment fees are first applied to bills on the Account. For example, if bills are issued every three months and the billingOffset is 0, then the charge is applied to the first bill (at three months); if set to 1, it's applied to the next bill (at six months), and so on.

commitmentFeeDescription

string

A textual description of the Commitment fee.

commitmentUsageDescription

string

A textual description of the Commitment usage.

overageDescription

string

A textual description of the overage charges.

commitmentFeeBillInAdvance

boolean

A boolean value indicating whether the Commitment fee is billed in advance (start of each billing period) or arrears (end of each billing period).

TRUE - bill in advance (start of each billing period).
FALSE - bill in arrears (end of each billing period).

billEpoch

string<date>

The starting date (in ISO-8601 date format) from which the billing cycles are calculated.

contractId

string

The unique identifier (UUID) for a Contract you've created for the Account and to which the Commitment has been added.

accountingProductId

string

The unique identifier (UUID) for the Product linked to the Commitment for accounting purposes.

feesAccountingProductId

string

Optional Product ID this Commitment's fees should be attributed to for accounting purposes.

drawdownsAccountingProductId

string

Optional Product ID this Commitment's consumptions should be attributed to for accounting purposes.

feeDates

object[]

Used for billing any outstanding Commitment fees on a schedule.

An array defining a series of bill dates and amounts covering specified service periods:

date - the billing date (in ISO-8601 format).
amount - the billed amount.
servicePeriodStartDate and servicePeriodEndDate - defines the service period the bill covers (in ISO-8601 format).

Show child attributes

childBillingMode

enum<string>

Commitment billing mode that only applies while using Parent/Child accounts. Used to control on which Bill the commitment fees and draw-downs appear:

PARENT_BREAKDOWN - A separate bill line item per Account and appear as separate line items on the Parent Bill - one per Child. (Default)
PARENT_SUMMARY - A single bill line item for all Accounts and appears as a single separate line item on the Parent Bill.
CHILD - Child Accounts are billed and appear as line items on each Child Account Bill.

Available options:

PARENT_SUMMARY,

PARENT_BREAKDOWN,

CHILD

lineItemTypes

enum<string>[]

Specifies the line item charge types that can draw-down at billing against the Commitment amount. Options are:

MINIMUM_SPEND
STANDING_CHARGE
USAGE
"COUNTER_RUNNING_TOTAL_CHARGE"
"COUNTER_ADJUSTMENT_DEBIT"

Available line item types for Commitments

Available options:

STANDING_CHARGE,

USAGE,

MINIMUM_SPEND,

COUNTER_RUNNING_TOTAL_CHARGE,

COUNTER_ADJUSTMENT_DEBIT

dtCreated

string<date-time>

The date and time (in ISO-8601 format) when the Commitment was created.

dtLastModified

string<date-time>

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

createdBy

string

The unique identifier (UUID) of the user who created this Commitment.

lastModifiedBy

string

The unique identifier (UUID) of the user who last modified this Commitment.

List Commitments

Search Commitments

⌘I