Skip to main content
PUT
/
organizations
/
{orgId}
/
commitments
/
{id}
Update Commitment
curl --request PUT \
  --url https://api.m3ter.com/organizations/{orgId}/commitments/{id} \
  --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": "PARENT_SUMMARY",
  "lineItemTypes": [
    "STANDING_CHARGE"
  ]
}
'
{
  "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"
    }
  ],
  "childBillingMode": "PARENT_SUMMARY",
  "lineItemTypes": [
    "STANDING_CHARGE"
  ],
  "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. The Organization represents your company as a direct customer of our service.

​
id
string
required

The unique identifier (UUID) for the Commitment to update.

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.
​
childBillingMode
enum<string>

If the Account is either a Parent or a Child Account, this specifies the Account hierarchy billing mode. The mode determines how billing will be handled and shown on bills for charges due on the Parent Account, and charges due on Child Accounts:

  • Parent Breakdown - a separate bill line item per Account. Default setting.

  • Parent Summary - single bill line item for all Accounts.

  • Child - the Child Account is billed.

Available options:
PARENT_SUMMARY,
PARENT_BREAKDOWN,
CHILD
​
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 updated Commitment

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

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

​
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).
​
childBillingMode
enum<string>

If the Account is either a Parent or a Child Account, this specifies the Account hierarchy billing mode. The mode determines how billing will be handled and shown on bills for charges due on the Parent Account, and charges due on Child Accounts:

  • Parent Breakdown - a separate bill line item per Account. Default setting.

  • Parent Summary - single bill line item for all Accounts.

  • Child - the Child Account is billed.

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.