M3m3ter-com
Bill

Lock Bill

Changed on

Lock the specific Bill identified by the given UUID. Once a Bill is locked, no further changes can be made to it.

NOTE: You cannot lock a Bill whose current status is PENDING. You will receive an error message if you try to do this. You must first use the Approve Bills call to approve a Bill before you can lock it.

put/organizations/{orgId}/bills/{id}/lock

Request

Path parameters

orgIdstring required

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

idstring required

The unique identifier (UUID) of the Bill to lock.

Response

Returns the locked Bill

purchaseOrderNumberstring

Purchase Order number linked to the Account the Bill is for.

externalInvoiceReferencestring

The reference ID to use for external invoice.

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

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

NOTE: To change the externalInvoiceDate setting for your Organization, you can use the Update OrganizationConfig call.

jsonStatementGeneratedboolean

Flag to indicate that the statement in JSON format has been generated for the Bill.

  • TRUE - JSON statement has been generated.
  • FALSE - no JSON statement generated.
csvStatementGeneratedboolean

Flag to indicate that the statement in CSV format has been generated for the Bill.

  • TRUE - CSV statement has been generated.
  • FALSE - no CSV statement generated.
statementStaleboolean

True if the existing bill statement (JSON or CSV) is marked as stale/outdated.

billTotalnumber

The sum total for the Bill.

totalDebitsnumber

The sum of debit line items on the bill.

totalCreditsnumber

The absolute sum of credit line items on the bill.

sequentialInvoiceNumberstring

The sequential invoice number of the Bill.

NOTE: If you have not defined a billPrefix for your Organization, a sequentialInvoiceNumber is not returned in the response. See Update OrganizationConfig

dtCreatedstring date-time

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

dtLastModifiedstring date-time

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

createdBystring

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

lastModifiedBystring

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

dtApprovedstring date-time

The DateTime when the bill was approved.

approvedBystring

The id of the user who approved this bill.

dtLockedstring date-time

The DateTime when the bill was locked.

lockedBystring

The id of the user who locked this bill.

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

The unique identifier (UUID) of the Account the Bill was generated for.

accountCodestring

The short code of the Account the Bill was generated for.

startDatestring date
endDatestring date
startDateTimeUTCstring date-time

Specifies the UTC time zone start date/time of the Bill's period in ISO 8601 format. Start dates are inclusive.

For example: "2022-02-01T00:00:00.000Z".

endDateTimeUTCstring date-time

Specifies the UTC time zone end date/time of the Bill's period in ISO 8601 format. End dates are exclusive.

For example: "2022-03-01T00:00:00.000Z".

billDatestring date

Based on the Billing cycle. Typically the first day of each Billing period. Bill date is determined by Organization Epoch setting for first Bill date and subsequent Bill dates and combined with the defined billing frequency - daily, weekly, monthly, or yearly.

For example: "2022-05-01".

Note that the Organization Epoch settings for first Bill date can be overridden at Account and Plan level.

dueDatestring date

Date the Bill is due. Determined by daysBeforeBillDue Organization setting and billDate. For example, if billDate for monthly billing cycle is 1st of each month and daysBeforeBillDue = 10, then dueDate = 11th of each month.

For example: "2022-05-11".

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

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 the Bill is created. If billingFrequency is MONTHLY and billFrequencyInterval is 3, then the Bill is created every three months.

timezonestring

The time zone used for the generated Bill.

currencystring

Bill Currency code. For example: USD, GBP or EUR.

lockedboolean

Boolean flag indicating whether the Bill is in a locked state. A locked a Bill can no longer be changed and is excluded from any billing runs:

  • TRUE - Bill is locked.
  • FALSE - Bill is unlocked.
createdDatestring date-time

Date/time the Bill was first calculated (in ISO 8601 format).

status'PENDING' | 'APPROVED'

Indicates whether the Bill has passed human/manual approval.

  • Pending - Bill has not yet been passed by a human reviewer.
  • Approved - Bill has been approved after manual review.
billJobIdstring

The unique identifier (UUID) of the BillJob responsible for generating the Bill.

lastCalculatedDatestring date-time

Date the Bill was last calculated (in ISO 8601 format).

Example response

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

Changes

  • 85c514abc692Revision changes
    • breaking

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

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • ac93d1a9e6d9Revision changes
    • warning

      added the new AD_HOC enum value to the // response property for the response status

    • info

      added the optional property to the response with the status