Skip to main content

Active Rating Use Cases

Zuora

Active Rating Use Cases

  1. Last updated
  2. Save as PDF

This feature is no longer available for new users. You can check Advanced Billing Consumption if you are interested in our up-to-date billing consumption features, such as Prepaid with Drawdown and Unbilled Usage.

This tutorial provides a list of typical use cases to help you understand how to better use REST API operations of the Active Rating feature.

Case I: Retrieving Unbilled Dollar Amount

You want to access active, hourly, or daily reports on the unbilled dollar amount to understand where the company is standing in terms of projected revenue, or to show values to end customers for visibility and predictability of the bill at the end of a billing period. You can use the REST API operations of the Active Rating feature to achieve this goal. 

For example, imagine a scenario where:

  • An end customer subscribes to a usage-based product rate plan charge with the Per Unit Pricing charge model.
  • The start date of the usage-based charge is 2016-01-01, and the end date is 2017-12-31.
  • The bill cycle day of the customer account is set to 1st of the month.
  • The billing period of the corresponding rate plan is set to monthly.
  • Two usage records were created in January. One started on 2017-01-02, and the other started on 2017-01-14.
  • The unit of measurement is set to Each.
  • The price per unit is $10.
  • The charge has been billed to 2017-01-01 for the end customer.
  • The end customer keeps using the service and usage records are uploaded continuously.

To get the date through which a customer has been billed for the charge, you can call Get subscriptions by key to get the value of the chargedThroughDate field in the response.

To get the unbilled amount, you can call Get rating results by charge to retrieve the consumed units in January.

The following is an example HTTP/JSON request.

GET https://rest.zuora.com/rating/ratedresults/charge/{chargeNumber}?fromDate=2017-01-01&toDate=2017-02-01

The following is an example JSON response of the preceding request.

{
    "dataSet": [
        {
            "id": "959283ee-e984-4fec-a67b-61d7110bc142",
            "startDate": "2017-01-01",
            "endDate": "2017-01-31",
            "amount": 350,
            "chargeNumber": "C-00000011",
            "subscriptionNumber": "A-S00000008",
            "accountNumber": "A00000006",
            "currency": "USD",
            "additionalInfo": {
                "uom": "Each",
                "quantity": 35
            },
            "ratedTime": "2017-12-01T00:16:58.119Z",
            "object": "RatedResult"
        }
    ],
    "cursor": null,
    "count": 1,
    "hasMore": false
}

Case II: Retrieving Historical Usage Over Time

You can use the REST API operations of the Active Rating feature to obtain source data, get a list of usage records, and then show a chart of current billing cycle usage to end customers.

For example, imagine a scenario where:

  • An end customer subscribes to a usage-based product rate plan charge with the Per Unit Pricing charge model.
  • The start date of the usage-based charge is 2016-01-01, and the end date is 2017-12-31.
  • The bill cycle day of the customer account is set to 1st of the month.
  • The billing period of the corresponding rate plan is set to monthly.
  • Two usage records were created in January. One started on 2017-01-02, and the other started on 2017-01-14.
  • The unit of measurement is set to Each.
  • The price per unit is $10.
  • The charge has been billed to 2017-01-01 for the end customer.
  • The end customer keeps using the service and usage records are uploaded continuously.

You can call Get rated usage by charge to retrieve the consumed units in January and then get the historical usage.

The following is an example HTTP/JSON request.

GET https://rest.zuora.com/rating/ratedusages/charge/{chargeNumber}?fromDate=2017-01-01&toDate=2017-02-01

The following is an example JSON response of the preceding request.

{
    "dataSet": [
        {
            "id": "0173cbb2-52f8-40b6-8b53-171f282956d3",
            "startDate": "2017-01-14",
            "amount": 200,
            "currency": "USD",
            "chargeNumber": "C-00000011",
            "subscriptionNumber": "A-S00000008",
            "accountNumber": "A00000006",
            "quantity": 20,
            "unitOfMeasure": "Each",
            "usageId": "3082011b-8548-4188-82b6-9a053f1e26ab",
            "ratedResultId": "959283ee-e984-4fec-a67b-61d7110bc142",
            "object": "RatedUsage"
        },
        {
            "id": "0aaf6df2-b5da-4c5e-a36b-172b21c8fa05",
            "startDate": "2017-01-02",
            "amount": 150,
            "currency": "USD",
            "chargeNumber": "C-00000011",
            "subscriptionNumber": "A-S00000008",
            "accountNumber": "A00000006",
            "quantity": 15,
            "unitOfMeasure": "Each",
            "usageId": "3a53067e-edb2-4d51-8887-7389db3b877e",
            "ratedResultId": "959283ee-e984-4fec-a67b-61d7110bc142",
            "object": "RatedUsage"
        }
    ],
    "cursor": null,
    "count": 2,
    "hasMore": false
}

Case III: Retrieving Total Rated Usage

You want to allow end customers to see their current usage progress. For example, you might want to show them the usage history progress bar based on the included units. This use case can also be used, if configured to retrieve rated usage information on a regular basis (for example, every 30 minutes) to send notifications both internally and externally.

For example, imagine a scenario where:

  • An end customer subscribes to a usage-based product rate plan charge with the Per Unit Pricing charge model.
  • The start date of the usage-based charge is 2016-01-01, and the end date is 2017-12-31.
  • The bill cycle day of the customer account is set to 1st of the month.
  • The billing period of the corresponding rate plan is set to monthly.
  • Two usage records were created in January. One started on 2017-01-02, and the other started on 2017-01-14.
  • The unit of measurement is set to Each.
  • The price per unit is $10.
  • The charge has been billed to 2017-01-01 for the end customer.
  • The end customer keeps using the service and usage records are uploaded continuously.

To retrieve the total rated usage in January or in a longer period, you can call any of the following operations to retrieve the consumed units:

The following is an example HTTP/JSON request of calling Get rating results by charge.

GET https://rest.zuora.com/rating/ratedresults/charge/{chargeNumber}?fromDate=2017-01-01&toDate=2017-02-01

The following is an example JSON response of the preceding request.

{
    "dataSet": [
        {
            "id": "959283ee-e984-4fec-a67b-61d7110bc142",
            "startDate": "2017-01-01",
            "endDate": "2017-01-31",
            "amount": 350,
            "chargeNumber": "C-00000011",
            "subscriptionNumber": "A-S00000008",
            "accountNumber": "A00000006",
            "currency": "USD",
            "additionalInfo": {
                "uom": "Each",
                "quantity": 35
            },
            "ratedTime": "2017-12-01T00:16:58.119Z",
            "object": "RatedResult"
        }
    ],
    "cursor": null,
    "count": 1,
    "hasMore": false
}

The following is an example HTTP/JSON request of calling Get rated usage by charge.

GET https://rest.zuora.com/rating/ratedusages/charge/{chargeNumber}?fromDate=2017-01-01&toDate=2017-02-01

The following is an example JSON response of the preceding request.

{
    "dataSet": [
        {
            "id": "0173cbb2-52f8-40b6-8b53-171f282956d3",
            "startDate": "2017-01-14",
            "amount": 200,
            "currency": "USD",
            "chargeNumber": "C-00000011",
            "subscriptionNumber": "A-S00000008",
            "accountNumber": "A00000006",
            "quantity": 20,
            "unitOfMeasure": "Each",
            "usageId": "3082011b-8548-4188-82b6-9a053f1e26ab",
            "ratedResultId": "959283ee-e984-4fec-a67b-61d7110bc142",
            "object": "RatedUsage"
        },
        {
            "id": "0aaf6df2-b5da-4c5e-a36b-172b21c8fa05",
            "startDate": "2017-01-02",
            "amount": 150,
            "currency": "USD",
            "chargeNumber": "C-00000011",
            "subscriptionNumber": "A-S00000008",
            "accountNumber": "A00000006",
            "quantity": 15,
            "unitOfMeasure": "Each",
            "usageId": "3a53067e-edb2-4d51-8887-7389db3b877e",
            "ratedResultId": "959283ee-e984-4fec-a67b-61d7110bc142",
            "object": "RatedUsage"
        }
    ],
    "cursor": null,
    "count": 2,
    "hasMore": false
}