Skip to main content

Usage Data Import


Usage Data Import

This feature is no longer available for new users. You can check Advanced Billing Consumption if you are interested in our up-to-date billing consumption features, such as Prepaid with Drawdown and Unbilled Usage.

You can import usage data by uploading a file through the Zuora UI or by calling the Import usage file operation.

A usage file can be in comma-separated value (.csv), Microsoft Excel (.xls), or ZIP format. The maximum size of a usage file is 20 MB. If the size of a usage file exceeds 20 MB, zip the usage file before uploading it. One ZIP file can only contain one CSV or Excel file.

The name of a usage file cannot be longer than 50 characters, including the length of the file name extension.

Usage File Format

If you have the Active Rating feature enabled, the columns you specified in the usage import file will be different from the old usage import file:

  • The ENDDATE column is removed from the usage import file. Because the end date is not used in the usage rating.
  • Specify the usage related subscription, charge, and account in the Tag column instead of specifying the related information in separate columns.
  • Specify the start date and time in the StartDateTime column instead of the start date in the STARTDATE column.
  • Support specifying the unique key for each usage record in the UniqueKey column.
  • Support specifying the group ID in the GroupId column used for usage rating by group.
  • Support specifying the custom fields in the usage import file.

The usage file must include the following fields in CSV, Excel, or ZIP format. The ZIP file can only have one CSV or Excel file. You can specify the column fields in random order.

Column Description Required?


The account number, for example, A00000001. The customer account must be the subscription owner.

The account number must be valid, and the account must be active.



Specifies which subscription, charge, or account the usage record is related to.

The value of this field can contain a maximum of 255 characters.

The value of this field should be in the following formats:

  • SubscriptionNumber:value
  • ChargeNumber:value
  • AccountNumber:value

If the value of this field is in the AccountNumber:value format, the value must be the same as the value of the AccountNumber field.

If the value of this field is in the ChargeNumber:value format, the value must be the same as the value of the UnitOfMeasure field corresponding to the usage charge.

The subscription number, charge number, and account number must be active, and the subscription cannot be in Draft status.

The customer account must be the subscription and charge owner.



The units to measure the usage consumption.

The value of this field is case insensitive.



The start date and time when this usage is consumed. For example, 2017-03-14T21:32:37Z.

Date format:  YYYY-MM-DDTHH:MM:SS[+ -]HH:MM 

See supported date and time format.



The number of units the usage record is used.



The description of the usage record.

The description can contain a maximum of 200 characters.



A unique key of the usage record. You can define the unique key for each usage record. This field is optional. It helps you prevent duplicate usage records created accidentally.



The group ID used for usage rating by group. Zuora groups the usage records based on the group ID when you choose the Custom Group option for usage rating.

The Usage Rating by Group feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support.

CustomFields.field_name The value of the custom fields. Use the custom field name to replace field_name. No

Sample Usage File

You can download the sample usage file and replace the sample data with your usage data in the file.