M3m3ter-com
BillJob

Create Recalculation BillJob

Changed on

Create a new BillJob specifically to recalculate existing bills for a given Organization.

This operation is essential when adjustments or corrections are required in previously calculated bills. The recalculated bills when the BillJob is complete can be checked in the m3ter Console Bill Management page or queried by using the List Bills operation.

NOTE:

  • Response Schema. The response schema for this call is dynamic. This means that the response might not contain all of the parameters listed. If set to null,the parameter is hidden to help simplify the output as well as to reduce its size and improve performance.
post/organizations/{orgId}/billjobs/recalculate

Request

Path parameters

orgIdstring required

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

Request body

versioninteger

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.
billIdsstring[] required

The array of unique identifiers (UUIDs) for the Bills which are to be recalculated.

Response

Returns the recalculated BillJob

idstring required

The UUID of the entity.

versioninteger

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.
lastDateInBillingPeriodstring date

Specifies the date (in ISO 8601 format) of the last day in the billing period, defining the time range for the associated Bills.

For example: "2023-03-24".

billingFrequency'DAILY' | 'WEEKLY' | 'MONTHLY' | 'ANNUALLY' | 'AD_HOC'

Defines how often Bills are generated.

  • Daily. Starting at midnight each day, covering a twenty-four hour period following.
  • Weekly. Starting at midnight on a Monday morning covering the seven-day period following.
  • Monthly. Starting at midnight on the morning of the first day of each month covering the entire calendar month following.
  • Annually. Starting at midnight on the morning of the first day of each year covering the entire calendar year following.
  • Ad_Hoc. Use this setting when a custom billing schedule is used for billing an Account, such as for billing of Prepayment/Commitment fees using a custom billing schedule.
billFrequencyIntervalinteger

How often Bills are issued - used in conjunction with billingFrequency.

For example, if billingFrequency is set to Monthly and billFrequencyInterval is set to 3, Bills are issued every three months.

billDatestring date

The specific billing date (in ISO 8601 format), determining when the Bill was generated.

For example: "2023-01-24".

externalInvoiceDatestring date

For accounting purposes, the date set at Organization level to use for external invoicing with respect to billing periods - two options:

  • FIRST_DAY_OF_NEXT_PERIOD (Default). Used when you want to recognize usage revenue in the following period.
  • LAST_DAY_OF_ARREARS. Used when you want to recognize usage revenue in the same period that it's consumed, instead of in the following period.

For example, if the retrieved Bill was on a monthly billing frequency and the billing period for the Bill is September 2023 and the External invoice date is set at FIRST_DAY_OF_NEXT_PERIOD, then the externalInvoiceDate will be "2023-10-01".

dueDatestring date

The due date (in ISO 8601 format) for payment of the Bill.

For example: "2023-02-24".

accountIdsstring[]

An array of UUIDs representing the end customer Accounts associated with the BillJob.

billIdsstring[]

An array of Bill IDs related to the BillJob, providing references to the specific Bills generated.

targetCurrencystring

The currency code used for the Bill, such as USD, GBP, or EUR.

timezonestring

Specifies the time zone used for the generated Bills, ensuring alignment with the local time zone.

yearEpochstring date

The starting date (epoch) for Yearly billing frequency (in ISO 8601 format), determining the first Bill date for yearly Bills.

monthEpochstring date

The starting date (epoch) for Monthly billing frequency (in ISO 8601 format), determining the first Bill date for monthly Bills.

weekEpochstring date

The starting date (epoch) for Weekly billing frequency (in ISO 8601 format), determining the first Bill date for weekly Bills.

dayEpochstring date

The starting date (epoch) for Daily billing frequency (in ISO 8601 format), determining the first Bill date for daily Bills.

status'PENDING' | 'INITIALIZING' | 'RUNNING' | 'COMPLETE' | 'CANCELLED'

The current status of the BillJob, indicating its progress or completion state.

totalinteger

The total number of Bills or calculations related to the BillJob.

pendinginteger

The number of pending actions or calculations within the BillJob.

type'CREATE' | 'RECALCULATE'

Specifies the type of BillJob.

  • Create when creating a new Bill.
  • Recalculate when recalculating an existing Bill.
dtCreatedstring date-time

The date and time (in ISO 8601 format) when the BillJob was first created.

dtLastModifiedstring date-time

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

createdBystring

The unique identifier (UUID) for the user who created the BillJob.

lastModifiedBystring

The unique identifier (UUID) for the user who last modified this BillJob.

Example response

{
  "currencyConversions": [
    {
      "from": "EUR",
      "to": "USD",
      "multiplier": 1.12
    }
  ],
  "timezone": "UTC"
}

Changes

  • 85c514abc692Revision changes
    • breaking

      the request property type changed from no type to object

    • breaking

      the response's property type changed from no type to object for status

  • 9f9e5f3dbde7Revision changes
    • breaking

      the response property //// became optional for the status