# Usage (with Active Rating) **Note:** The Usage (with Active Rating) operations are part of the [Active Rating](https://knowledgecenter.zuora.com/CB_Billing/J_Billing_Operations/H_Active_Rating) feature. You cannot use these operations with the [Usage](/v1-api-reference/api/usage) operations. If a 500 or 502 error occurs when you call any of the Usage (with Active Rating) operations, the first troubleshooting step is to retry the call. ## Create usage records - [POST /usage](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/post_usagerecords.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Creates a single or multiple usage records for an account. The account that you want to create usage records for must have a corresponding usage-based rate plan charge. For more information about the usage data format, see Usage Data Import. ## Update usage record - [PUT /usage/{id}](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/put_usagerecord.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Updates certain information of a specified usage record. Note that you can only update usage records that are not billed. ## Get usage record - [GET /usage/{id}](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_usagerecord.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Retrieves information about a specific usage record. ## Delete usage record - [DELETE /usage/{id}](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/delete_usagerecord.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Deletes a usage record. Note that you can only delete usage records with the Pending or Rated status. ## Query usage records - [GET /usage/query](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_usagerecordsquery.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Retrieves information about usage records. You can specify certain response fields you want to retrieve by specifying the fields and filters query parameters. By default, all the response fields are returned in the response. ## Query usage records in stream - [GET /usage/stream-query](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_usagerecordsstreamquery.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Retrieves information about usage records in a stream without pagination. You can specify certain response fields you want to retrieve by sepcifying the fields and filters query parameters. By default, all the reponse fields are returned in the response. The value of the filters parameter must be URL-encoded. If you want to use a plus sign + in the endpoint URL, you must replace the plus sign + with %2B. For example, if you use /usage/stream-query?filters=(status='Pending' and startDateTime > '2018-04-04T13:32:37+08:00') in the endpoint URL, an error occurs. You have to use /usage/stream-query?filters=(status='Pending' and startDateTime > '2018-04-04T13:32:37%2B08:00') instead. ## Import usage file - [POST /usage-imports](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/post_importusagefile.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Imports usage data by uploading a usage file. A usage file can be in comma-separated value (.csv), Microsoft Excel (.xls), or ZIP format. The maximum size of a usage file in CSV, Excel, or ZIP format to be uploaded 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. For more information about the usage file format, see Usage Data Import. ## Get usage imports - [GET /usage-imports](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_usageimports.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Retrieves the information about all the usage import files, such as the processing status of the usage import files, the total number of usage records that are validated, and the number of usage records with validation errors. The response is in descending order by the date and time of the updatedOn field. ## Get details of usage import - [GET /usage-imports/{id}/detail](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_usageimportdetails.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Retrieves the detailed information about a specified usage import file. ## Get status of usage import - [GET /usage-imports/{id}/status](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_usageimportstatus.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Retrieves the processing status of a specified usage import file. ## Download usage import file - [GET /usage-imports/{id}/import-file](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_downloadusageimportfile.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Downloads a usage import file with the specified usage import ID. ## Download usage import failure file - [GET /usage-imports/{id}/errors](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_downloadusageimportfailurefile.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Downloads the corresponding usage import failure file when a usage file fails to be imported. Usage import failure files are only available for usage import files in VALIDATED_FAILED status. The downloaded usage import failure file is in ZIP format, and contains the error information about each usage record failing to be imported. ## Download usage file template - [GET /usage-imports/templates/{fileType}](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_downloadusagefiletemplate.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Downloads a usage file template. The usage file template can be in comma-separated value (.csv) or Microsoft Excel (.xls) format. After the template is downloaded, you can create a usage file based on the template and add usage records to the file. ## Get rating results by account - [GET /rating/rated-results/account/{accountNumber}](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_ratingresultsbyaccount.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Retrieves the rating result of all the usage charges associated with the specified customer account. The response returns the rating amount of the charges based on billing period. By default, the response data is displayed in descending order by updated time. You can specify the date range for which you want to rate in the fromDate and toDate query parameters. For example: /rated-results/account/accountNumber?fromDate=2016-08-01&toDate=2016-08-21 ## Get rating results by subscription - [GET /rating/rated-results/subscription/{subscriptionNumber}](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_ratingresultsbysubscripiton.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Retrieves the rating result of all the usage charges associated with the specified subscription. The rating is based on billing period. You can specify the date range for which you want to rate in the fromDate and toDate query parameters. For example: /rated-results/subscription/subscriptionNumber?fromDate=2016-08-01&toDate=2016-08-21 ## Get rating results by charge - [GET /rating/rated-results/charge/{chargeNumber}](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_ratingresultsbycharge.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Retrieves the rating result of all the usage charges associated with the specified rate plan charge. The rating is based on billing period. You can specify the date range for which you want to rate in the fromDate and toDate query parameters. For example: /rated-results/charge/chargenNumber?fromDate=2016-08-01&toDate=2016-08-21 ## Get rated usage by account - [GET /rating/rated-usages/account/{accountNumber}](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_usageratingbyaccount.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Retrieves the rating result of the usage records associated with the specified customer account. The response returns the rating result of each usage record. You can specify the date range for which you want to get the usage rating result in the fromDate and toDate query parameters. For example: /rated-usages/account/accountNumber?fromDate=2016-08-01&toDate=2016-08-21 ## Get rated usage by subscription - [GET /rating/rated-usages/subscription/{subscriptionNumber}](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_usageratingbysubscription.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Retrieves the rating result of the usage records associated with the specified subscription. The response returns the rating result of each usage record. You can specify the date range for which you want to get the rating result in the fromDate and toDate query parameters. For example: /rated-results/subscription/subscriptionNumber?fromDate=2016-08-01&toDate=2016-08-21 ## Get rated usage by charge - [GET /rating/rated-usages/charge/{chargeNumber}](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_usageratingbycharge.md): Note: This operation is available only if Active Rating is enabled. The Active Rating feature is in development. If you wish to have access to the feature, submit a request at Zuora Global Support. Retrieves the rating result of the usage records associated with the specified charge. The response returns the rating result of each usage record. You can specify the date range for which you want to get the rating result in the fromDate and toDate query parameters. For example: /rated-results/charge/chargenNumber?fromDate=2016-08-01&toDate=2016-08-21 ## Get Usage custom field definition - [GET /fields/definitions/Usage](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/get_customfieldsdefinitioninglobalnamespace.md): Note: This operation is available only if Active Rating and Custom Fields services are enabled. The Custom Fields service is in Limited Availability and Active Rating is in development. If you wish to have access to the services, submit a request at Zuora Global Support. ## Set schema of Usage custom field definition - [PUT /fields/definitions/Usage](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/put_customfieldsdefinitioninglobalnamespace.md): Note: This operation is available only if Active Rating and Custom Fields services are enabled. The Custom Fields service is in Limited Availability and Active Rating is in development. If you wish to have access to the services, submit a request at Zuora Global Support. ## Limitations This custom fields definition has the following limitations: * The maximum number of characters for custom field API name is 64. * The maximum number of characters for custom field label (label) is 64. * The maximum number of characters for custom field description is 250. * The maximum number of picklist options is 250. * Custom field names are case sensitive and must contain __c as the suffix. If you want to add new custom fields or update existing custom fields, you must include the schema of all existing custom fields in the request body. ## Delete schema of Usage custom field definition - [DELETE /fields/definitions/Usage](https://developer.zuora.com/archive/active-rating/active-rating-api/usage-(with-active-rating)/delete_customfieldsdefinitioninglobalnamespace.md): Note: This operation is available only if Active Rating and Custom Fields services are enabled. The Custom Fields service is in Limited Availability and Active Rating is in development. If you wish to have access to the services, submit a request at Zuora Global Support. Before calling this operation, you must delete all data stored in the custom fields. To delete all data stored in custom fields that are part of Active Rating, use Delete usage record. When you delete the schema of a custom fields definition, Zuora sets "schema": {} and "type": "_internal" for the custom fields definition.