Update Commitment
Modify a specific Commitment.
Update the details of the Commitment with the given UUID. Use this endpoint to adjust Commitment parameters such as the fixed amount, overage surcharge percentage, or associated contract details.
Path parameters
The unique identifier (UUID) for your Organization. The Organization represents your company as a direct customer of our service.
The unique identifier (UUID) for the Commitment to update.
Request body
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.
The unique identifier (UUID) for the end customer Account the Commitment is added to.
The unique identifier (UUID) for the Product Plan used for billing Commitment fees due.
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.
The start date of the Commitment period in ISO-8601 format.
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
The currency used for the Commitment. For example: USD.
The total amount that the customer has committed to pay.
The amount that the customer has already paid upfront at the start of the Commitment service period.
The amount to be billed in the first invoice.
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
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.
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.
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.
A textual description of the Commitment fee.
A textual description of the Commitment usage.
A textual description of the overage charges.
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).
The starting date (in ISO-8601 date format) from which the billing cycles are calculated.
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.
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
Optional Product ID this Commitment fees should be attributed to for accounting purposes
Optional Product ID this Commitment consumptions should be attributed to for accounting purposes
Commitment billing mode that only applies while using parent/child accounts, used to configure on which bill the commitment fees and draw downs end up.
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.
Response
Returns the updated Commitment
The UUID of the entity.
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.
The unique identifier (UUID) for the end customer Account the Commitment is added to.
The unique identifier (UUID) for the Product Plan used for billing Commitment fees due.
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.
The start date of the Commitment period in ISO-8601 format.
The end date of the Commitment period in ISO-8601 format.
The currency used for the Commitment. For example, 'USD'.
The total amount that the customer has committed to pay.
The amount that the customer has already paid upfront at the start of the Commitment service period.
The amount to be billed in the first invoice.
The total amount of the Commitment that the customer has spent so far.
The percentage surcharge applied to the usage charges that exceed the Commitment amount.
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.
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.
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.
A textual description of the Commitment fee.
A textual description of the Commitment usage.
A textual description of the overage charges.
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).
The starting date (in ISO-8601 date format) from which the billing cycles are calculated.
The unique identifier (UUID) for a Contract you've created for the Account and to which the Commitment has been added.
The unique identifier (UUID) for the Product linked to the Commitment for accounting purposes.
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.
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"
The date and time (in ISO-8601 format) when the Commitment was created.
The date and time (in ISO-8601 format) when the Commitment was last modified.
The unique identifier (UUID) of the user who created this Commitment.
The unique identifier (UUID) of the user who last modified this Commitment.