Skip to main content

Unbilled Usage


Unbilled Usage

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.

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.

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.


You need to enable Orders to use this feature.

Supported charge models

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

  • Per Unit
  • Tiered Pricing
  • Volume 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 create or update a usage record in the following ways:

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.

The “upsert” action will update an existing record identified by the unique key field or insert a new record if the unique key doesn’t exist. This operation can only be done via usage import. You cannot use any Usage REST APIs to perform this operation.

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.