# Usage Consumption of a billable service or resource (such as database storage space or bundles of emails sent) provides the basis for some charge models - simple usage, tiered pricing, or volume pricing. To make this work, usage must be tracked in the system and usage charges must be calculated and invoiced. Usage is always billed in arrears - for example, you might bill customers in February for their January usage. Usage can be billed on a recurring monthly, quarterly, semi-annual, or annual basis. ## Upload a usage file - [POST /v1/usage](https://developer.zuora.com/v1-api-reference/api/usage/post_usage.md): 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 uploaded usage 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 length of the file name must not exceed 50 characters. The file size must not exceed 4MB. See Downloading the Usage Template to learn about how to download the usage file template. At the completion of the upload, before the file contents are actually being processed, 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 has failed. To manage the information after a successful upload, use the web-based UI. #### Dynamic pricing usage charges When the uploaded file contains rows that reference a product rate plan charge configured for dynamic pricing, the upload is rejected and those rows are not imported. Legacy Billing usage import does not support sending usage to dynamic pricing usage charges. To send usage to a dynamic pricing usage charge, use Mediation to ingest and rate the events. Mediation generates usage records that are later consumed by Billing, instead of relying on this bulk upload endpoint. ### Usage File Format The usage file uses the following headings: | Heading | Description | Required | |-----------------|--------|----------| | 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. | Yes | | UOM | Enter the unit of measure. This must match the UOM for the usage. | Yes | | QTY | Enter the quantity. | 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. | 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. Note: The value of this column is optional, but the column header is required. | No | | 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. Note: The value of this column is optional, but the column header is required. To use this field, you must set the X-Zuora-WSDL-Version request header to 146 or higher. Otherwise, an error occurs. | No | | 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. Note: The value of this column is optional, but the column header is required. | No | | 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. 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. Note: The value of this column is optional, but the column header is required. | No | | DESCRIPTION | Enter a description for the charge. | No | | UNIQUE_KEY | Enter a specific identifier for this usage record. Note: This Heading is supported by the following features: Prepaid with Drawdown, and Unbilled Usage. See Upload usage record with unique key for more information. | No | ## Retrieve usage rate detail for an invoice item - [GET /v1/invoices/invoice-item/{invoice-item-id}/usage-rate-detail](https://developer.zuora.com/v1-api-reference/api/usage/get_usage_rate_detail_by_invoice_item.md): Use this REST API operation to retrieve the usage rate detail for an invoice item to understand how the total amount is calculated. The information is the same as the Rate Detail presented on PDF invoices. Notes and limitations: - Do not support the Overage Charge Model, Tiered with Overage Charge Model, and Multi-attribute Pricing Charge Model. - Do not support invoices in Cancelled or Reversed status. - Do not support Active rating. - In terms of rating group options, only the Usage rating by billing period is supported. - Do not support On-demand usage rating. - Tax calculation is not involved. ## CRUD: Create a usage record - [POST /v1/object/usage](https://developer.zuora.com/v1-api-reference/api/usage/object_postusage.md): Creates a usage record. ## CRUD: Delete a usage record - [DELETE /v1/object/usage/{id}](https://developer.zuora.com/v1-api-reference/api/usage/object_deleteusage.md): Deletes a usage record. Usage records that are associated with a dynamic pricing usage charge cannot be deleted with this legacy Billing endpoint. When a delete request targets such a record, the operation fails and the usage record is not removed. Operations on dynamic pricing usage are supported only via Mediation-driven flows. ## CRUD: Retrieve a usage record - [GET /v1/object/usage/{id}](https://developer.zuora.com/v1-api-reference/api/usage/object_getusage.md): Retrieve a usage record. ## CRUD: Update a usage record - [PUT /v1/object/usage/{id}](https://developer.zuora.com/v1-api-reference/api/usage/object_putusage.md): Updates a usage record. Updating usage records that are associated with a dynamic pricing usage charge is not supported through this endpoint. The request fails and the record is not updated. Use Mediation-based flows to manage such usage.