Knowledge Center

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

ACCOUNT_ID

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

UOM

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

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. Date format is based on locale of the current user.

Default date format:  MM/DD/YYYY 

Required? yes

ENDDATE

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

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.

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

CHARGE_ID

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

DESCRIPTION

Enter a description for the charge. 

Required? No

 

Request

  • Production: POST https://api.zuora.com/rest/v1/usage
  • API Sandbox: POST https://apisandbox-api.zuora.com/rest/v1/usage

Request body

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

Response

success

Contains true if successful, otherwise false.

processId

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

reasons

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

code

Eight-digit numeric error code

message

Description of the error

size

The size of the uploaded file in bytes

checkImportStatus

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.

Example

CURL request:

##
## Upload Usage
##
echo
echo "=============Upload Usage============"
echo
# 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

Response:

{
  "success": true,
  "checkImportStatus": "https://api.zuora.com/rest/v1/usage/2c92c8f83dcbd8b1013dcce1159900cc/status",
  "size": 316
}
Last modified
23:06, 4 Sep 2016

Tags

Classifications

(not set)