Active Rating API (2020-02-10)

E-mail: docs@zuora.com

Usage (with Active Rating)

Note: The Usage (with Active Rating) operations are part of the Active Rating feature. You cannot use these operations with the 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

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.

Request
header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Content-Type
required
string

The type of the request content.

  • If you create multiple usage records, you must specify the value of this parameter to application/vnd.zuora.usage-bulk+json.

  • If you create a single usage record, you do not need to specify this field.

Request Body schema: application/vnd.zuora.usage-bulk+json;charset=UTF-8
required
Array of objects (data)

(Conditional) This field is only used for creating multiple usage records. If you create a single usage record, you do not need to specify the data field in the request.

An array of usage records information.

Responses
200

OK

400

Bad Request

409

Conflict

500

Internal Server Error

post/usage
Request samples
application/vnd.zuora.usage-bulk+json;charset=UTF-8
{
  • "data": [
    ]
}
Response samples
{
  • "data": [
    ]
}

Update usage record

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.

Request
path Parameters
id
required
string

The ID of the usage record you want to update.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Request Body schema: application/json; charset=utf-8
required
object (customFields)

Container for custom fields.

description
string <= 200 characters

The description of the usage record.

quantity
number <double>

The number of units the usage record is used.

startDateTime
string <date-time>

The start date and time when the usage is consumed. See supported date and time format.

unitOfMeasure
string <= 50 characters

The definable unit used to measure consumed usage.

Responses
200

OK

400

Bad Request

404

Not Found

409

Conflict

500

Internal Server Error

put/usage/{id}
Request samples
application/json; charset=utf-8
{
  • "quantity": "15",
  • "unitOfMeasure": "Each",
  • "startDateTime": "2017-01-14T21:00:00+08:00",
  • "description": "Disk usage for A00002689"
}
Response samples
{
  • "id": "string"
}

Get usage record

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.

Request
path Parameters
id
required
string

The ID of the usage record you want to retrieve.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

404

Not Found

500

Internal Server Error

get/usage/{id}
Response samples
{
  • "accountNumber": "string",
  • "createdBy": "string",
  • "createdOn": "2019-08-24T14:15:22Z",
  • "customFields": {
    },
  • "description": "string",
  • "fileName": "string",
  • "groupId": "string",
  • "id": "string",
  • "importId": "string",
  • "quantity": 0.1,
  • "startDateTime": "2019-08-24T14:15:22Z",
  • "status": "Pending",
  • "tag": "string",
  • "uniqueKey": "string",
  • "unitOfMeasure": "string",
  • "updatedBy": "string",
  • "updatedOn": "2019-08-24T14:15:22Z"
}

Delete usage record

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.

Request
path Parameters
id
required
string

The ID of the usage record you want to delete.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

404

Not Found

500

Internal Server Error

delete/usage/{id}
Response samples
{
  • "success": true
}

Query usage records

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.

Request
query Parameters
fields
string

The fields of the usage records you want to retrieve. By default, all the fields in the Responses section are returned.

Use commas to separate the field names. You can specify any fields described in the Responses section. For example: /usage/query?fields=tag,quantity,id

filters
string

This parameter restricts the data returned in the response. You can use this parameter to supply a dimension you want to filter on.

A single filter uses the following form:

field_name operator field_value

Supported operators: =, !=, >, <, >=, <=, IS NULL, IS NOT NULL, IN (The letters are not case sensitive.)

You can specify any fields except for the custom fields described in the Responses section. Filters can be combined using the AND boolean logic. For example: field_name operator field_value AND field_name operator field_value

Currently, the fields in filters must include at least one of the following fields: accountNumber, status, uniqueKey, and updatedOn.

Examples:

  • /usage/query?filters= (id ='035e35bd-880a-47c9-99df-830143b13aed' AND status='Pending')

  • /usage/query?fields=tag,id&filters= (quantity > 10 AND status='Pending')

  • /usage/query?filters=(status in ('Pending','Rated'))

page
integer <int32>
Default: 0

The index number of the page you want to retrieve. By default, the first page is returned in the response.

pageSize
integer <int32> [ 25 .. 2000 ]
Default: 100

The maximum number of rows in a page to return in a response.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

500

Internal Server Error

get/usage/query
Response samples
{
  • "data": [
    ]
}

Query usage records in stream

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.

Request
query Parameters
fields
string

The fields of the usage records you want to retrieve. By default, all the fields in the Responses section are returned.

Use commas to separate the field names. You can specify any fields described in the Responses section. For example: /usage/stream-query?fields=tag,quantity,id,customFields.age

filters
string

This parameter restricts the data returned in the response. You can use this parameter to supply a dimension you want to filter on.

A single filter uses the following form:

field_name operator field_value

Supported operators: =, !=, >, <, >=, <=, IS NULL, IS NOT NULL, IN (The letters are not case sensitive.)

You can specify any fields, including the custom fields, described in the Responses section. Filters can be combined using the AND boolean logic. For example: field_name operator field_value AND field_name operator field_value

Currently, the fields in filters must include at least one of the following fields: accountNumber, unitOfMeasure, status, uniqueKey, and updatedOn.

Examples:

  • /usage/stream-query?filters= (id ='035e35bd-880a-47c9-99df-830143b13aed' AND status='Pending' AND customFields.age=20)

  • /usage/stream-query?fields=tag,id&filters= (quantity > 10 AND unitOfMeasure = 'GB')

  • /usage/stream-query?filters=(status in ('Pending','Rated'))

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

500

Internal Server Error

get/usage/stream-query
Response samples
{
  • "data": [
    ]
}

Import usage file

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.

Request
header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Request Body schema: multipart/form-data
required
file
required
string <binary>

The path and name of the usage file to be imported.

description
string

The description of the usage file to be imported.

Responses
200

OK

400

Bad Request

500

Internal Server Error

post/usage-imports
Request samples 
curl -X POST -H "Authorization: Bearer 66c7fc29ea984b049284d10f6b6328f5' -F "file=@UsageData.csv" -F "description=import testing" "https://rest.zuora.com/usage-imports"
Response samples
{
  • "id": "string",
  • "status": "PENDING"
}

Get usage imports

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.

Request
query Parameters
page
integer <int32>
Default: 0

The index number of the page you want to retrieve. By default, the first page is returned in the response.

pageSize
integer <int32> [ 25 .. 2000 ]
Default: 100

The maximum number of rows in a page to return in a response.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

500

Internal Server Error

get/usage-imports
Response samples
{
  • "data": [
    ]
}

Get details of usage import

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.

Request
path Parameters
id
required
string

The ID of the usage import.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

404

Not Found

500

Internal Server Error

get/usage-imports/{id}/detail
Response samples
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "status": "PENDING",
  • "error": "string",
  • "processStart": "2019-08-24T14:15:22Z",
  • "processEnd": "2019-08-24T14:15:22Z",
  • "totalCount": 0,
  • "errorCount": 0,
  • "importedCount": 0,
  • "createdBy": "string",
  • "createdOn": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "updatedOn": "2019-08-24T14:15:22Z"
}

Get status of usage import

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.

Request
path Parameters
id
required
string

The ID of the usage import.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

404

Not Found

500

Internal Server Error

get/usage-imports/{id}/status
Response samples
{
  • "status": "PENDING"
}

Download usage import file

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.

Request
path Parameters
id
required
string

The ID of the usage import.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

404

Not Found

500

Internal Server Error

get/usage-imports/{id}/import-file
Response samples
No sample

Download usage import failure file

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.

Request
path Parameters
id
required
string

The ID of the usage import.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

404

Not Found

500

Internal Server Error

get/usage-imports/{id}/errors
Response samples
No sample

Download usage file template

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.

Request
path Parameters
fileType
required
string

The type of the usage file template to be downladed.

Enum: "csv" "xls"
header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

get/usage-imports/templates/{fileType}

Get rating results by account

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

Request
path Parameters
accountNumber
required
string

The account number. For example, A00000001.

query Parameters
fromDate
string <date>

The start date of the date range for which you want to rate. The date must be in yyyy-mm-dd format. For example, 2007-12-03.

You can specify this parameter to restrict the data returned in the response. Make sure you specify a valid date in this query parameter:

  • If you only specify the fromDate query parameter but do not specify the toDate query parameter:

    endDate > fromDate

  • If you specify both the fromDate and toDate query parameters:

    startDate <= toDate and endDate > fromDate

startDate is the start date of the rating result. endDate is the end date of the rating result.

toDate
string <date>

The end date of the date range for which you want to rate. The date must be in yyyy-mm-dd format. For example, 2007-12-03.

You can specify this parameter to restrict the data returned in the response. Make sure you specify a valid date in this query parameters:

  • If you only specify the toDate query parameter but do not specify the fromDate query parameter:

    startDate <= toDate

  • If you specify both the fromDate and toDate query parameters:

    startDate <= toDate and endDate > fromDate

startDate is the start date of the rating result. endDate is the end date of the rating result.

cursor
string

The cursor indicator of the data page you want to retrieve. By default, the first page of data is returned in the response. If more data pages are available, the operation returns true in the hasMore response body field. The cursor response body field specifies the cursor indicator of the next page of data. If there is no data after the current page, the value of cursor is null.

pageSize
integer <int32> [ 25 .. 2000 ]
Default: 100

The maximum number of rows in a page to return in a response.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

400

Bad Request

404

Not Found

500

Internal Server Error

get/rating/rated-results/account/{accountNumber}
Response samples
{
  • "dataSet": [
    ],
  • "cursor": "string",
  • "count": 0,
  • "hasMore": true
}

Get rating results by subscription

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

Request
path Parameters
subscriptionNumber
required
string

The subscription number. For example, A-S00000001.

query Parameters
fromDate
string <date>

The start date of the date range for which you want to rate. The date must be in yyyy-mm-dd format. For example, 2007-12-03.

You can specify this parameter to restrict the data returned in the response. Make sure you specify a valid date in this query parameter:

  • If you only specify the fromDate query parameter but do not specify the toDate query parameter:

    endDate > fromDate

  • If you specify both the fromDate and toDate query parameters:

    startDate <= toDate and endDate > fromDate

startDate is the start date of the rating result. endDate is the end date of the rating result.

toDate
string <date>

The end date of the date range for which you want to rate. The date must be in yyyy-mm-dd format. For example, 2007-12-03.

Make sure you specify a valid date in this query parameters:

  • If you only specify the toDate query parameter but do not specify the fromDate query parameter:

    startDate <= toDate

  • If you specify both the fromDate and toDate query parameters:

    startDate <= toDate and endDate > fromDate

startDate is the start date of the rating result. endDate is the end date of the rating result.

cursor
string

The cursor indicator of the data page you want to retrieve. By default, the first page of data is returned in the response. If more data pages are available, the operation returns true in the hasMore response body field. The cursor response body field specifies the cursor indicator of the next page of data. If there is no data after the current page, the value of cursor is null.

pageSize
integer <int32> [ 25 .. 2000 ]
Default: 100

The maximum number of rows in a page to return in a response.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

400

Bad Request

404

Not Found

500

Internal Server Error

get/rating/rated-results/subscription/{subscriptionNumber}
Response samples
{
  • "dataSet": [
    ],
  • "cursor": "string",
  • "count": 0,
  • "hasMore": true
}

Get rating results by charge

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

Request
path Parameters
chargeNumber
required
string

The charge number. For example, C-00000001.

query Parameters
fromDate
string <date>

The start date of the date range for which you want to rate. The date must be in yyyy-mm-dd format. For example, 2007-12-03.

You can specify this parameter to restrict the data returned in the response. Make sure you specify a valid date in this query parameter:

  • If you only specify the fromDate query parameter but do not specify the toDate query parameter:

    endDate > fromDate

  • If you specify both the fromDate and toDate query parameters:

    startDate <= toDate and endDate > fromDate

startDate is the start date of the rating result. endDate is the end date of the rating result.

toDate
string <date>

The end date of the date range for which you want to rate. The date must be in yyyy-mm-dd format. For example, 2007-12-03.

Make sure you specify a valid date in this query parameters:

  • If you only specify the toDate query parameter but do not specify the fromDate query parameter:

    startDate <= toDate

  • If you specify both the fromDate and toDate query parameters:

    startDate <= toDate and endDate > fromDate

startDate is the start date of the rating result. endDate is the end date of the rating result.

cursor
string

The cursor indicator of the data page you want to retrieve. By default, the first page of data is returned in the response. If more data pages are available, the operation returns true in the hasMore response body field. The cursor response body field specifies the cursor indicator of the next page of data. If there is no data after the current page, the value of cursor is null.

pageSize
integer <int32> [ 25 .. 2000 ]
Default: 100

The maximum number of rows in a page to return in a response.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

400

Bad Request

404

Not Found

500

Internal Server Error

get/rating/rated-results/charge/{chargeNumber}
Response samples
{
  • "dataSet": [
    ],
  • "cursor": "string",
  • "count": 0,
  • "hasMore": true
}

Get rated usage by account

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

Request
path Parameters
accountNumber
required
string

The account number. For example, A00000001.

query Parameters
fromDate
string <date>

The start date of the date range for which you want to get the rating result. The date must be in yyyy-mm-dd format. For example, 2007-12-03.

You can specify this parameter to restrict the data returned in the response. Make sure you specify a valid date in this query parameter:

  • If you only specify the fromDate query parameter but do not specify the toDate query parameter:

    startDate >= fromDate

  • If you specify both the fromDate and toDate parameters:

    startDate >= fromDate and startDate <= toDate

startDate is the start date when the usage is consumed in your tenant time zone.

toDate
string <date>

The end date of the date range for which you want to get the rating result. The date must be in yyyy-mm-dd format. For example, 2007-12-03.

Make sure you specify a valid date in this query parameters:

  • If you only specify the toDate query parameter but do not specify the fromDate query parameter:

    startDate <= toDate

  • If you specify both the fromDate and toDate query parameters:

    startDate >= fromDate and startDate <= toDate

startDate is the start date when the usage is consumed in your tenant time zone.

cursor
string

The cursor indicator of the data page you want to retrieve. By default, the first page of data is returned in the response. If more data pages are available, the operation returns true in the hasMore response body field. The cursor response body field specifies the cursor indicator of the next page of data. If there is no data after the current page, the value of cursor is null.

pageSize
integer <int32> [ 25 .. 2000 ]
Default: 100

The maximum number of rows in a page to return in a response.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

400

Bad Request

404

Not Found

500

Internal Server Error

get/rating/rated-usages/account/{accountNumber}
Response samples
{
  • "dataSet": [
    ],
  • "cursor": "string",
  • "count": 0,
  • "hasMore": true
}

Get rated usage by subscription

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

Request
path Parameters
subscriptionNumber
required
string

The subscription number. For example, A-S00000001.

query Parameters
fromDate
string <date>

The start date of the date range for which you want to get the rating result. The date must be in yyyy-mm-dd format. For example, 2007-12-03.

You can specify this parameter to restrict the data returned in the response. Make sure you specify a valid date in this query parameter:

  • If you only specify the fromDate query parameter but do not specify the toDate query parameter:

    startDate >= fromDate

  • If you specify both the fromDate and toDate parameters:

    startDate >= fromDate and startDate <= toDate

startDate is the start date when the usage is consumed in your tenant time zone.

toDate
string <date>

The end date of the date range for which you want to get the rating result. The date must be in yyyy-mm-dd format. For example, 2007-12-03.

Make sure you specify a valid date in this query parameters:

  • If you only specify the toDate query parameter but do not specify the fromDate query parameter:

    startDate <= toDate

  • If you specify both the fromDate and toDate query parameters:

    startDate >= fromDate and startDate <= toDate

startDate is the start date when the usage is consumed in your tenant time zone.

cursor
string

The cursor indicator of the data page you want to retrieve. By default, the first page of data is returned in the response. If more data pages are available, the operation returns true in the hasMore response body field. The cursor response body field specifies the cursor indicator of the next page of data. If there is no data after the current page, the value of cursor is null.

pageSize
integer <int32> [ 25 .. 2000 ]
Default: 100

The maximum number of rows in a page to return in a response.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

400

Bad Request

404

Not Found

500

Internal Server Error

get/rating/rated-usages/subscription/{subscriptionNumber}
Response samples
{
  • "dataSet": [
    ],
  • "cursor": "string",
  • "count": 0,
  • "hasMore": true
}

Get rated usage by charge

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

Request
path Parameters
chargeNumber
required
string

The charge number. For example, C-00000001.

query Parameters
fromDate
string <date>

The start date of the date range for which you want to get the rating result. The date must be in yyyy-mm-dd format. For example, 2007-12-03.

You can specify this parameter to restrict the data returned in the response. Make sure you specify a valid date in this query parameter:

  • If you only specify the fromDate query parameter but do not specify the toDate query parameter:

    startDate >= fromDate

  • If you specify both the fromDate and toDate parameters:

    startDate >= fromDate and startDate <= toDate

startDate is the start date when the usage is consumed in your tenant time zone.

toDate
string <date>

The end date of the date range for which you want to get the rating result. The date must be in yyyy-mm-dd format. For example, 2007-12-03.

Make sure you specify a valid date in this query parameters:

  • If you only specify the toDate query parameter but do not specify the fromDate query parameter:

    startDate <= toDate

  • If you specify both the fromDate and toDate query parameters:

    startDate >= fromDate and startDate <= toDate

startDate is the start date when the usage is consumed in your tenant time zone.

cursor
string

The cursor indicator of the data page you want to retrieve. By default, the first page of data is returned in the response. If more data pages are available, the operation returns true in the hasMore response body field. The cursor response body field specifies the cursor indicator of the next page of data. If there is no data after the current page, the value of cursor is null.

pageSize
integer <int32> [ 25 .. 2000 ]
Default: 100

The maximum number of rows in a page to return in a response.

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

400

Bad Request

404

Not Found

500

Internal Server Error

get/rating/rated-usages/charge/{chargeNumber}
Response samples
{
  • "dataSet": [
    ],
  • "cursor": "string",
  • "count": 0,
  • "hasMore": true
}

Get Usage custom field definition

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.

Request
header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

400

Bad Request

get/fields/definitions/Usage
Response samples
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "string",
  • "createdById": "string",
  • "updatedById": "string",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "updatedDate": "2019-08-24T14:15:22Z",
  • "schema": { }
}

Set schema of Usage custom field definition

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.

Request
header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

If-Match
string

The expected ETag of the resource. You can use this header to perform a conditional request. Zuora responds with 412 Precondition Failed if the ETag of the resource does not match the value of this header.

Request Body schema: application/json; charset=utf-8
required

The schema for the custom fields definition.

The schema must be the complete custom fields definition that includes all Usage custom fields.

The schema must conform to the JSON Schema specification.

If the value of the type path parameter is Usage, the schema must have "type": "object". Each property in the schema must not have "type": "object" or "type": "array".

property name*
additional property
any
Responses
200

OK

400

Bad Request

412

Precondition Failed

put/fields/definitions/Usage
Request samples
application/json; charset=utf-8
{
  • "title": "Usage",
  • "type": "object",
  • "properties": {
    },
  • "required": [
    ]
}
Response samples
"http://example.com"

Delete schema of Usage custom field definition

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.

Request
header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Responses
200

OK

400

Bad Request

delete/fields/definitions/Usage
Response samples
"http://example.com"