Skip to main content

How Do I Load Usage Information?


How Do I Load Usage Information?

Usage based charge models in Zuora Billing allow for the conversion of units into money, usually based on a tiered pricing model. During the customer account's next billing run, Zuora will scoop up and (if there is more than one usage record for an account) aggregate all the relevant usage records and apply the charge model to convert the loaded units into monies owed. Usage billing is always done in arrears. That is, you bill for usage after your customer has used (consumed) the units.

If you are new to the topic of usage with Zuora, review the following articles first:

In Zuora, usage is measured by units and there are no restrictions for what is measured by your units. For example, a unit can represent a seat, a license, or even a gigabyte of storage. You can also create new units of measure at any time by going to Billing > Customize Units of Measure.

Usage Load Options

Two usage load methods are supported:

  • Use an Excel spreadsheet or comma-separated value file (.csv) file to manually load usage via the Zuora user interface (UI). See Adding Usage Data for details on how to load usage and to understand how the usage load record attributes are named and what their purpose is.
  • Using the Zuora API to create usage objects.

Please note there is no screen to enter individual usage records using the Zuora UI, you can only load a file or use the API to add usage records. All usage data must be in the Zuora specified format. You must utilize your metering system's reporting features to report the data in the necessary format or utilize an ETL or data mapping tool to convert the metered data to Zuora's format.

Therefore if regular, such as daily, uploads are needed you should either be prepared to load a file each day or develop an automated process to do the equivalent using the Zuora API. Use cases on working with the Zuora Usage object can be found in our API documentation.

Do You Need To Load Usage Daily?

Before rushing into daily loads you should review your actual business need, starting with what do your Units of Measure (UOMs) represent in the real world? As we've noted above Zuora will sum the usage for a particular charge, subscription or account, but Zuora doesn't currently provide any other aggregation functions such as average, min or max -  only summation. So if you're measuring something like average disk space usage over a month, your external metering system must only supply one value for that UOM, for each account, and for that time period. So if your customer is on a monthly billing plan you would load one record per month for that account, for that UOM. Zuora's billing engine will then convert the UOM amount in that record to the appropriate charge automatically.

As a result many customers prefer to do all usage value derivation external to Zuora and only load one usage record per charge, per billing period regardless of usage type. This often results in one load file per month, which is more manageable using a manual process.

Accidentally Load The Same Usage Records Twice

Zuora Usage objects always have one of two statuses: Pending Process or Processed. When initially loaded all objects have a Pending Process' state, but after having been processed by the billing engine and turned into a charge, the status is updated to Processed. Once processed by the billing engine, the associated amount has been converted to a charge on an invoice and can no longer be deleted. If the status is Pending Process you can use the Zuora UI or the API to remove usage records. 

Deleting Usage Records

Using the UI go to the Usage page (Billing Operations > Usage) and you'll see a list of all recently loaded usage.  If you only need to remove an individual record click on the Status  (must be Pending Process) for that record and you will be presented with a screen that allows you to edit or delete that usage record. If you loaded an entire file in error, just click on the file name in the File Name column (next to Status) and you'll be taken to a screen where you can delete all the usage loaded by that file.  

The Zuora API also allows you delete usage records by specifying the appropriate usage object identifiers, see Deleting Usage in our API documentation for details. Zuora provides an ImportId field for each usage record that can be used to easily identify which records came from a specific import.

Extracting Uploaded Usage and Notifications

You can now export loaded usage using the Full Data Sources feature (currently in controlled release, please contact Zuora Global Support if you are interested in this feature). There are also two Import Notifications available, one for successful and one for failed usage imports. These notifications are found by going to Billing > Setup Profiles, Notifications, and Email Templates. See the following notifications: Import Processed | Completed Status and Import Processed | Completed Status.