Post usage

Knowledge Center > API > REST API > REST API Reference > Usage > Post usage

Post usage

This REST API reference describes how to post or import usage data for one or more accounts in the CSV format. There are no path or query parameters. The data is uploaded using the HTTP multipart/form-data POST method and applied to the user's tenant. 

How this REST API Call Works

The content of the upload file must follow the format used by the UI import tool. It must be a comma-separated (CSV) file with a corresponding .csv extension. The file size must not exceed 4MB. Click here to download the usage file template.

At the completion of the upload, before actually processing the file contents, the API returns a response containing the byte count of the received file and a URL for checking the status of the import process.  Of the five possible results displayed at that URL (Pending, Processing, Completed, Canceled, and Failed) only a Completed status indicates that the import was successful.  The operation is atomic; if any record fails, the file is rejected.  In that case, the entire import is rolled back and all stored data is returned to its original state.

To view the actual import status, enter the resulting status URL from the checkImportStatus response using a tool such as POSTMAN. This additional step provides more information about why the import may have failed.

To manage the information after a successful upload, use the web-based UI.

Upload File Format

The upload file uses the following headings:

Heading Description


Enter the account number, e.g., the default account number, such as A00000001, or your custom account number.  Although this field is labeled as Account_Id, it is not the actual Account ID nor Account Name.

Required? yes


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

Required? yes


Enter the quantity. 

Required? yes


Enter the start date of the usage.  This date determines the invoice item service period the associated usage is billed to. Date format is based on locale of the current user.

Default date format:  MM/DD/YYYY 

Required? yes


Enter the end date of the usage.  This is not used in calculations for usage billing and is optional. Date format is based on locale of the current user.

Default date format:  MM/DD/YYYY

Required? yes


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.

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.

Required? yes


Enter the charge number (not the charge name). You can see the charge ID, e.g., C-00000001, when you add your rate plan to your subscription and view your individual charges. See Adding Products and Rate Plans for additional information.

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. 

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

Required? yes


Enter a description for the charge. 

Required? No



  • Production: POST
  • API Sandbox: POST

Request body

The HTTP request body contains the upload file, formatted for the HTTP multipart/form-data upload.



Contains true if successful, otherwise false.


Internal process ID to assist Zuora support. Only returned if success is false.


Information on one or more reasons for the result. Only returned if success is false.


Eight-digit numeric error code


Description of the error


The size of the uploaded file in bytes


URL for checking the status of the import operation.  Possible status values at this URL are: Pending, Processing, Completed, Canceled, Failed.  Only a status of Completed indicates that the file contents were imported successfully.


CURL request:

## Upload Usage
echo "=============Upload Usage============"
# Don't forget add '@' before the file name.
curl -i -k -H "apiAccessKeyId:$USER_NAME" -H "apiSecretAccessKey:$PASSWORD" -H "Accept:application/json" --form "file=@UsageFileFormat.csv" -X POST $BASE_URL/v1/usage


  "success": true,
  "checkImportStatus": "",
  "size": 316
Last modified



(not set)