Sign in
Bill

Preview Bill

Preview the current Bill for a specific account.

This endpoint is designed to provide a preview of the Bill for exactly one account, allowing you to review charges, frequencies, and other details before finalization. Required parameters include:

  • accountIds - exactly 1 account must be specified for previewing a Bill.
  • billingFrequency
  • billFrequencyInterval

Other request parameters are optional. If version is not specified, the latest version of the Bill is previewed.

post/organizations/{orgId}/bills/preview

Path parameters

orgIdstring required

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

Query parameters

debugboolean nullable

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

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

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.

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.

Example request

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

Response

Returns the Bill preview

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.

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
accountCodestring
startDatestring date
endDatestring date
startDateTimeUTCstring date-time
endDateTimeUTCstring date-time
billDatestring date
dueDatestring date
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
timezonestring
currencystring
lockedboolean
createdDatestring date-time
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
lastCalculatedDatestring date-time

Example response

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

Changes

Changed in 6 of the 10 revisions of this API.22115

  • ac93d1a9e6d911See the full diff
    • ●

      added the new AD_HOC enum value to the lineItems/items/lineItemType response property for the response status 200

      response-property-enum-value-added

    • ○

      added the optional property statementStale to the response with the 200 status

      response-optional-property-added

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 9f9e5f3dbde729See the full diff
    • ▲

      the response property allOf[AbstractBillResponse]/allOf[AbstractResponse]/version became optional for the status 200

      response-property-became-optional

    • ▲

      the response property allOf[AbstractResponse]/version became optional for the status 200

      response-property-became-optional

    • ○

      added the optional property approvedBy to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property dtApproved to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property dtLocked to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property lineItems/items/accountingProductCode to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property lineItems/items/accountingProductId to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property lineItems/items/accountingProductName to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property lineItems/items/additional to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property lineItems/items/usagePerPricingBand/items/convertedBandSubtotal to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property lockedBy to the response with the 200 status

      response-optional-property-added

    This revision also has 53 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 9beb1e1df3bd1See the full diff
    • ○

      added the optional property lineItems/items/chargeId to the response with the 200 status

      response-optional-property-added

    This revision also has 11 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 6c3e1a3cfb8f1See the full diff
    • ○

      added the optional property lineItems/items/group to the response with the 200 status

      response-optional-property-added

  • d064a12d0d932See the full diff
    • ○

      the timezone request property default value UTC was added

      request-property-default-value-added

    • ○

      the timezone response's property default value UTC was added for the status 200

      response-property-default-value-added

    This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 9433593378b5201See the full diff
    • ●

      removed the optional property accountCode from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property accountId from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property billDate from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property billFrequencyInterval from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property billJobId from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property billingFrequency from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property createdDate from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property currency from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property currencyConversions from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property dueDate from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property endDate from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property endDateTimeUTC from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property id from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property lastCalculatedDate from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property locked from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property startDate from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property startDateTimeUTC from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property status from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property timezone from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property version from the response with the 200 status

      response-optional-property-removed

    • ○

      added AbstractBillResponse AbstractResponse to the response body allOf list for the response status 200

      response-body-all-of-added

    This revision also has 41 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog