Skip to main content

Import usage data

Zuora

Import usage data

  1. Last updated
  2. Save as PDF

You can add usage data by either uploading (importing) a file from the Zuora UI and APIs.

Downloading the usage template

To upload usage charges, you must first download and populate the Export Usage File template.

To download the template:

  1. Navigate to Billing > Usage in the left-hand navigation section.
  2. At the upper-right corner of the page, click add new usage records.
  3. Next to Download a usage file template, click either Excel or CSV. The template will open in the selected format. 

Usage file format

The usage file type is in Microsoft Excel (.xls) or comma-separated value (.csv) format.

We recommend that you use the following CSV format variations to import usage data:

  • MS-DOS Comma Separated from Microsoft Excel
  • Windows Comma Separated from Microsoft Excel
  • Comma Separated Values from Microsoft Excel
  • Comma-separated Values from Google Sheets

To download a copy of the correct usage file format, click the file type link next to Download a usage file template.

The usage file format has the following columns. 

Column Description

ACCOUNT_ID

Enter the account number. For example, the default account number, such as A00000001, or your custom account number. 

Be sure to use the account number not the Account ID or Account Name. 

Required? yes

UOM

Enter the unit of measure. This must match the UOM for the usage that is set up in Billing > Customize Units of Measure.

Required? yes

QTY

Enter the quantity. 

Required? yes

STARTDATE

Enter the start date of the usage.  This date determines the invoice item service period the associated usage is billed to. The date format is based on locale of the current user. For example, the start date format is MM/DD/YYYY for the en_US locale, and is DD/MM/YYYY for the en_GB locale.

Required? yes

ENDDATE

Enter the end date of the usage.  This is not used in calculations for usage billing and is optional. The date format is based on locale of the current user. For example, the end date format is MM/DD/YYYY for the en_US locale, and is DD/MM/YYYY for the en_GB locale.

Required? The value of this column is optional, but the column header is required in the usage file.
PRODUCT_RATE_PLAN_CHARGE_ID

Enter a product rate plan charge number so that you can charge your customer with a dynamic usage charge for the corresponding uploaded usage record.

Required? The value of this column is optional, but the column header is required in the usage file.

SUBSCRIPTION_ID

Enter the subscription number or subscription name.

If you created the subscription in the Zuora application, Zuora created a number automatically in a format similar to: A-S00000001

If you do not provide a value for this field, the associated usage will be added to all subscriptions for the specified Account that use this Unit Of Measure.

Required? The value of this column is optional, but the column header is required in the usage file. If your Accounts can have multiple subscriptions and you do not want double or triple counting of usage, you must specify the Subscription or Charge ID in each usage record.

CHARGE_ID

Enter the charge number, for example, C-00000001, when you add your rate plan to your subscription and you view your individual charges. See Adding Products and Rate Plans for additional information.

This field is related to the Charge Number on the subscription rate plan.

Required? The value of this column is optional, but the column header is required in the usage file. If your Accounts can have multiple subscriptions and you do not want double or triple counting of usage, you must specify the specific Subscription or Charge ID in each usage record.

DESCRIPTION

Enter a description for the charge. 

Required? The value of this column is optional, but the column header is required in the usage file.
UNIQUE_KEY

Note: This column is available only if you have the Prepaid with Drawdown feature enabled. 

Enter a specific identifier for this usage record. It accepts a string less than 255 characters, for example, UK123. If not specified, its value will be ‘null’ by default. When you upload a usage record and specify the UNIQUE_KEY, the system will check if there is an existing usage record with the same Unique_Key. See this article for details.  

Required? No

Do not create a custom field with the same name as the standard Zuora field for the Usage object. For example, having two STARTDATE fields in a usage file. If you do, the system will throw an error saying the usage file is missing required columns.

STARTDATE and ENDDATE Format and User Locale

The format used for STARTDATE and ENDDATE depends on the locale of the current user. This format is not controlled by the locale that you set for your Zuora tenant. For example, if the user's locale is set to English (United Kingdom) or English (Australia), the date format would be DD/MM/YYYY.

See Managing users for information about configuring the locale setting. 

Importing Usage Data

To import usage data:

  1. Navigate to Billing > Usage in the left-hand navigation section.
  2. At the upper-right corner of the page, click add usage records. 
  3. From this page, you can download an empty usage upload template. Click your desired file format next to Download a usage file template.
  4. Edit the file to add usage data. See "Usage file format" above for more information about the fields in the template and their meaning.

Do not delete any columns in the Usage template file. Although the values are optional and the fields are empty, the Usage file will not import successfully if any of the column field names in the downloaded Usage template do not exist in the uploaded Usage file.

  1. Click Choose File and select the file that you want to import. The file must be in the Zuora Billing usage file format. 
  2. Click submit.

After importing the usage file, the usage uploads are automatically set to the Pending status. This status indicates that the usage is waiting to be billed. Once they are billed (when you post an invoice that contains these usage charges), the status will be updated to Processed.

See Reviewing and posting bill runs for information about posting an invoice. See Do I need to upload usage daily? for more information about automating usage loading.

Mass usage upload

Zuora allows you to perform a mass, asynchronous upload of usage records using the Zuora UI or the Zuora API. 

  • You can import zipped comma-separated value (.csv ) files using the Zuora UI or API. In addition, you can import zipped Microsoft Excel (.xls) files using the Zuora UI. You can import a single file at a time, up to 4 MB in size.
  • You can download the import result in a single, zipped .csv file.
  • You can query records that have been imported successfully using the ImportId field of the Usage object.
  • You can use import notifications to send the import result to one or more users. 

Do not perform any processes that will use this data, such as bill runs, until the usage import is complete. 

Handling failures

Two types of failures may occur when uploading usage information:

  • Upload failure: If the file cannot be uploaded, Zuora will return you to the usage upload page. Verify that the file matches the usage file format, and then upload the file again. In this case, Zuora does not load any information. This type of failure can occur if the file type is not recognized, the file is not encoded in UTF-8, or if the file is too large (greater than 4 MB). 
  • Import failure: If Zuora cannot import the data successfully, the system will return a Failed Status | Import Processed notification. If this occurs, verify that the file is correct, and then upload the file again.  See How to handle usage import failure for more information.