Skip to main content

Unbilled Usage


Unbilled Usage

Unbilled Usage enables you to access the usage and due amounts of consumption-based subscriptions before charges are billed. After usage records are uploaded for a charge, you can view the accumulated usage and updated amount in near real-time. The rating results are calculated at the usage-charge level. 

The unbilled usages and amounts will be updated automatically when new usage records are added to charges. Usage and amounts will also be re-rated if changes are made to subscriptions, for example, the value of the billing cycle day of a charge is changed.

In addition, you can upload usage records after service periods are billed, or even after the accounting periods that contain the billed service periods are closed. For more information, see Late Usage.

Also, you can upload usage records of negative quantity to adjust the previously uploaded usage records. For more information, see Negative Quantity Usage.

You can set threshold notifications against Unbilled Usage to notify your customers when usage has reached certain thresholds. Use the Rating Result base object to set event triggers. For more information, see Custom Events.

This feature also enables you to retrieve the consumption information, such as the unbilled charges, usage quantities, and amounts due, through the Rating Result data source.


Unbilled Usage is part of the Advanced Consumption Billing feature. You need to purchase the feature to use it. Contact your Zuora Customer Success Manager for assistance.

You must have either Orders or Orders Harmonization enabled on your tenant before using the Unbilled Usage feature.

Additionally, if you want to enable either of the following functions in the Unbilled Usage feature, submit a request at Zuora Global Support:

  • Unbilled Usage supports evergreen subscriptions.
  • Unbilled Usage supports your Production environments' Tiered with Overage Pricing charge models. The Sandbox environments have it enabled by default.

Supported charge models

When the Unbilled Usage feature is enabled, the following usage charge models are supported:

  • Per Unit Pricing
  • Tiered Pricing
  • Volume Pricing
  • Tiered with Overage Pricing

View unbilled usages on Zuora UI

With this feature enabled, you can view unbilled usages on the subscription details page through Zuora UI.

In the Unbilled Usage section, each row represents the unbilled usage of a charge for an unbilled billing period. The following information is available:

  • Charge: Name of the charge
  • Service Period: The billing period of the unbilled charge
  • UOM: Unit of measurement of the charge
  • Quantity: Accumulated usage
  • Amount: Rated due amount

Note: If you have enabled the reinvented UI, you can view the unbilled usage of each charge by clicking the View Unbilled Usage link under the charge.

Once a charge is billed for a billing period, the corresponding unbilled usage item will disappear from the table.

For drawdown usage charges, only after the entire prepaid balance is consumed, the remaining usage will be generated and displayed for the billing period in which the usage is added to. 

For non-drawdown usage charges, unbilled usage will be updated right after the usage is uploaded.

Upload usage record with unique key

A unique key is a specific identifier for a usage record. You can use it to upsert a usage record, that is, to update an existing record identified by the unique key field or insert a new record if the unique key doesn’t exist.

You can use the unique key in the following ways:

Note: The upsert operation can only be done via usage import. You cannot use any Usage REST APIs to perform this operation.

Unique key is not required for a usage record, but if you include it, the system will check whether a usage record with the same unique key already exists in the database.

  • If No, the system will create a new usage record.
  • If Yes and the existing usage record was deleted, the system will recover the usage record and update it with the new one.
  • If Yes and the existing usage record was not deleted,
    • If the two records are identical, the system will ignore the new usage record and keep the existing one.
    • If the two records differ in Account ID, Subscription ID, or Charge ID, the system will block this operation because those fields cannot be updated.
    • If the two records differ in UOM, Start Date, Quantity, End Date, or Description, the system will update the existing usage record with the new one.

Notes and limitations

The Unbilled Usage feature currently has the following limitations:

  • Rating usage records individually is not compatible with the Unbilled Usage feature. For more information about the feature of rating usage records individually, see Rate aggregated or individual usage.
  • Rating Group can only be one of By Billing PeriodBy Usage Start Date, or By Usage Upload.
  • You must refresh the data if the settings or billing periods are changed after the unbilled usage rating results are generated.
  • The Change the owner of a subscription order action is allowed if all the guided usage under this subscription is billed. Note that invoice ownership transfer is supported.
  • Note the supported charge models by Unbilled Usage. The unsupported charges will not have unbilled results generated.
  • For subscriptions containing usage records that are not uploaded at the rate plan charge level (guiding usage), upon order actions that update the existing rate plan charge, the unbilled amount of those usage will not be re-calculated per the updated charge automatically. To view the re-calculated unbilled amount:
    • If the usage record has a unique key, re-import this record after the rate plan charge updates. This is because upsert is only supported via file import.
    • If the usage record doesn’t have a unique key, you must first delete the usage record and then re-upload the record.
  • For existing subscriptions, you need an enablement process to fully utilize the unbilled usage feature. You must complete the enablement and migration process to avoid bill run errors, after which the unbilled usage information will be present for existing usage charges for the supported usage charge models.
    Only new usage records that belong to the next billing periods after enablement can enjoy unbilled usage. The existing billing periods that have yet to be billed will continue to use the old rater, not the new unbilled usage rater.