Run a Calculation to Match a Bill

This How-to shows you how to match a customer’s existing utility bill using the On-Demand Cost Calculation API.

The first step for many Genability Signal customers is to reproduce one or more of their customer’s historical bills. By successfully matching your customer’s bill, you can be confident you have their usage and important billing attributes correct when presenting historical cost data. And when you move onto running what-if calculations you’ll know you have successfully defined the customer and their baseline usage.

In this How To we recommend a simple three step process to calculate and match a bill:

1. Select the correct Tariff, and optionally the tariff properties too
2. Make a Bill Match Calculate Call
3. Using the results that came back, calibrate and re-run your Calculate call as needed.

Typically, steps 1 and 3 take longer when provisioning a site (e.g. the first bill) than they do for subsequent bills. If you are matching multiple bills at once, we recommend to do them in chronological order.

Select the Correct Tariff

It’s key that you run the calculation against the right tariff! We actually have a whole separate How To on that. Read Pick the Right Tariff and then come back here!

How to make the Bill Match Calculate Call

Let’s jump straight in with an example of how to make a call. It’s the best way to explain what to do. Here we are using our On-Demand Cost Calculator with specific input parameters that allow us to match a bill. The approach is similar if you are using the Account Cost Calculator, which is for our Switch customers.

In the example below, we calculate a monthly bill for the Florida Power & Light’s General - Demand tariff.

POST /rest/v1/ondemand/calculate

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
    "masterTariffId": 85116,
    "fromDateTime": "2015-11-15T00:00:00-08:00",
    "toDateTime": "2015-12-17T00:00:00-08:00",
    "billingPeriod": true,
    "minimums": true,
    "groupBy": "MONTH",
    "detailLevel": "CHARGE_TYPE_AND_TOU",
    "fields": "ext",
    "expected": {
    "totalCost": 19731.30,
    "kWh": 154324,
    "kW": 354
  },
    "propertyInputs": [ {
        "fromDateTime": "2015-11-15T00:00:00-08:00",
        "toDateTime": "2015-12-17T00:00:00-08:00",
        "keyName": "consumption",
        "unit": "kWh",
        "dataValue": "154324"
    },{
        "fromDateTime": "2015-11-15T00:00:00-08:00",
        "toDateTime": "2015-12-17T00:00:00-08:00",
        "keyName" : "demand",
        "unit" : "kW",
        "dataValue":"354"
    }],
"rateInputs":[
    {
         "rateGroupName":"Taxes",
         "rateName":"Utility Tax",
         "chargeType":"TAX",
         "rateBands":[
            {
               "rateAmount": 0.04,
               "rateUnit":"PERCENTAGE"
            }]
    }]
}

So let’s break this request down:

Passing in the Usage Values from the Bill

When you are working from a utility bill, it will likely include the customer’s consumption (kWh) and peak demand (kW or kVA) values for the billing period. To the extent that the tariff includes rates that vary by season or Time of Use (TOU), the kWh and kW values might be correspondingly broken out. Whatever the granularity of usage data, you will want to use it in your on-demand calculation in order to get the best match accuracy.

For each usage input you will want to create an object in the propertyInputs. For example, if you have a bill that looks like this:

Then your calculate call should include the following objects in your propertyInputs:

1. keyName - Consumption for kWh and kVARh values, demand for kW, kVA and kVAR values.
2. unit - What the dataValue is measured in.
3. dataValue - The amount of consumption/demand for that period and date range.
4. Optional - Date Range (fromDateTime, toDateTime) - This designates the range of time when electricity was consumed or the demand peak was reached. For most bills this will be identical to the billing date range. However, when a tariff has rates that vary by Season, bills that cross two seasons will have a date range for each season. Or when bills cross two tariff versions, the utility may have a date range for each tariff version.

Passing in a tax rate

To include the customer’s tax rate, you will need to add a rate to the tariff when you make your calculation request. This is done through a rateInputs object. For more information on including tax rates in your calculations, review our How-to on Including Taxes.

Passing in other billing properties

You will need to pass rate criteria properties (such as the connection type) in order to drive which rates are applied and to improve the overall accuracy of your calculation. The calculator will default these tariff properties to the most likely values but you can override these values with the customer’s bill specifics. There is often an indication of the customer’s connection type either in the tariff code or somewhere else on the bill.

In the section below entitled “Are you sure you have the correct Rate Criteria Properties?” we show you how to double check the results in order to refine these values, but you can also look at our Rate Criteria How-To for more details on this important step.

Requesting the appropriate level of details back

1. groupBy - At what time period (MONTH, DAY, HOUR) would you like the calculation results returned. Grouping by month with “billingPeriod”: true provides the same view of the charges as most utility bills.
2. detailLevel - How would you like the charges grouped. Options range from the most granular (RATE) to the most general (TOTAL). Other options include CHARGE_TYPE (consumption, demand, fixed, other) and CHARGE_TYPE_AND_TOU (consumption, demand, fixed and other split out by Season/Time of Use). RATE provides the most detail, but CHARGE_TYPE_AND_TOU usually matches the utility bill most closely.
3. fields - By adding "fields": "ext" to your call, you get back the maximum amount of information with your calculation.

The How To Use the Calculator’s detailLevel & groupBy fields article is a great source of further detail on alternate options.

Calibrate your Calculate Call

Now you will review the results returned from your calculation request. Let’s say you expected $35,356.29 but the results returned a calculated cost of $36,815.87. It’s time to calibrate your calculate call so you can rerun the calculation. Below we highlight common issues that can prevent an exact bill match. Here’s some systematic things to check.

Are you sure you have the correct Tariff?

Double-check you selected the right Tariff. Many utilities have tariffs with similar names and tariff codes. Between the tariff code, tariff name and tariff properties, Genability provides as much information as possible to help you select the correct tariff.

Double Check your Date Range

Warning! Billing date ranges can be trickier than you think. The dates printed on the bill could refer to the start of the day, or the end of the day, and we find different utilities follow different rules. This is important because the calculate API calculates costs using the rate that was effective when the usage occurred. Making a mistake on the date range can result in the usage being assigned to the wrong rate.

TIP - Many utilities include the number of billing days in the period on the bill. This is the best way to confirm you set your date range correctly.

When you pass a date without a timezone offset to the Calculate API, Genability understands this as the very beginning of the day (10/15/2017 = 2017-10-15T00:00:00) in the tariff’s timezone. If you need to include the usage from the final day of the billing period, simply add a day to your date range when running a calculation.

Are you sure you have the correct Rate Criteria Properties?

Review what Rate Criteria Properties were defaulted - Most commercial and industrial tariffs can vary their pricing either based on the customer’s physical attributes (e.g. the voltage at which the site connects to the grid: connectionType) or optional programs in which the customer has enrolled (e.g. PG&E’s CARE program). If you do not specify these settings in your calculation, Genability will use the most likely setting for the property.

To review the rate criteria properties used, take a look at the assumptions section at the bottom of your calculation response. This will include all the tariff properties of type rate criteria on the tariff and indicate what values Genability defaulted. A defaulted tariff property will have an accuracy populated, with a value of less than 100 (typically 80). If you find an indicator on the bill that the defaulted value is incorrect, you will need to pass the new value as a propertyInput. When the tariff property value is specified as a propertyInput in the request, the tariff property will have an accuracy of 100 in the response.

Here is a snippet of the assumptions section of a calculation for PG&E’s E-TOU-A (masterTariffId: 3251054):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "keyName": "hasCAEnergySurchargeExemption",
    "displayName": "Has Energy Surcharge Exemption",
    "description": "Exemptions for CA Energy Surcharge apply to the following:\r\n1. Federal Agencies. American National Red Cross facilities. Energy consumed on Indian reservations\r\n4. Foreign consular employees. Federal Credit Unions",
    "dataType": "BOOLEAN",
    "fromDateTime": "2017-08-10T00:00:00-07:00",
    "toDateTime": "2017-08-11T00:00:00-07:00",
    "dataValue": "false",
    "accuracy": 80
},
{
    "keyName": "smartMeterOptOut",
    "displayName": "Has Smart Meter Opt-Out",
    "description": "Customers  who elect to opt-out of receiving a smart meter and choose to retain a non-smart meter, are subject to the Smart Meter Opt-Out fees.Smart Meter Opt-Out Customers are subject to one-time, up-front fee and a recurring monthly fee ",
    "dataType": "BOOLEAN",
    "fromDateTime": "2017-08-10T00:00:00-07:00",
    "toDateTime": "2017-08-11T00:00:00-07:00",
    "dataValue": "false",
    "accuracy": 80
},

You can tell that the default values are used for the “hasCAEnergySurchargeExemption” and “smartMeterOptOut” tariff properties since the accuracy is 80.

For more information on including Tariff Properties in your calculations, review our Rate Criteria Properties How-To.

Deregulated market requiring Contracted Rates?

Is this a deregulated market with Contracted Rates? By default, Genability includes the price-to-compare in its calculations. You may need to specify the supply rates contracted with a third-party supplier or exclude supply charges because those are covered on a separate bill. For more information, review our How-to on Contracted Rates.

Usage Data Granular Enough

As noted in the Billing Dates section, the date range you use in your calculation determines what rate is applied to which usage by the API. This ensures that your calculation results reflect the rates that were effective when the bill was generated.

However, this can cause an issue when the usage on the customer’s bill is not granular enough to run an accurate calculation. This can happen when 1) the billing period crosses a season boundary, 2) rates are updated in the middle of the billing period or 3) when the tariff has rates that vary by day (most of New York) or even hour (SCE’s RTP tariff).

To determine if the billing period crosses a season boundary, we recommend using our Time Of Use endpoint and/or our Season endpoint.

To determine if the rates are updated in the middle of the billing period, here are our recommendations:

(a) Use the On-Demand Cost Calculation API

When you run a calculation, the assumptions in the response will include the tariff versions used. Here is the calculation request for a Florida Power & Light bill with a date range of 12/12/2016 to 1/13/2017:

POST /rest/v1/ondemand/calculate

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
    "masterTariffId": 85116,
    "fromDateTime": "2016-12-12",
    "toDateTime": "2017-01-13",
    "billingPeriod": true,
    "minimums": true,
    "groupBy": "MONTH",
    "detailLevel": "CHARGE_TYPE_AND_TOU",
    "fields": "ext",
    "propertyInputs": [ {
        "fromDateTime": "2016-12-12",
        "toDateTime": "2017-01-13",
        "keyName": "consumption",
        "unit": "kWh",
        "dataValue": "135647"
    },{
        "fromDateTime": "2016-12-12",
        "toDateTime": "2017-01-13",
        "keyName" : "demand",
        "unit" : "kW",
        "dataValue":"456"
    }],
"rateInputs":[
    {
         "rateGroupName":"Taxes",
         "rateName":"Utility Tax",
         "chargeType":"TAX",
         "rateBands":[
            {
               "rateAmount": 0.04,
               "rateUnit":"PERCENTAGE"
            }]
    }]
}

You can determine two tariff versions are used in the calculation because the assumptions section includes two tariffIds:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "keyName": "tariffId",
    "dataType": "INTEGER",
    "fromDateTime": "2016-12-12T00:00:00-05:00",
    "toDateTime": "2017-01-01T00:00:00-05:00",
    "dataValue": "3253628",
    "accuracy": 100
},
{
    "keyName": "tariffId",
    "dataType": "INTEGER",
    "fromDateTime": "2017-01-01T00:00:00-05:00",
    "toDateTime": "2017-01-13T00:00:00-05:00",
    "dataValue": "3273719",
    "accuracy": 100
},

The first tariff version (tariffId of 3253628) was used between 12/12/2016 to 1/1/2017 and the second tariff version (tariffId of 3273719) was used between 1/1/2017 to 1/13/2017.

(b) Use the Tariff API

If you need the inputs before running a calculation, you can get the necessary information from the Tariff API.

Let’s use the Florida Power & Light bill with a date range of 12/12/2016 to 1/13/2017 as an example. Here is the request to retrieve the tariff using the effectiveOn parameter:

GET /rest/public/tariffs/85116?effectiveOn=2016-12-12

The response returns the tariff version that is effective at the start of the billing period. However, notice that there is an endDate of 2017-01-01:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
    "status": "success",
    "count": 1,
    "type": "Tariff",
    "results": [
        {
            "tariffId": 3253628,
            "masterTariffId": 85116,
            "tariffCode": "GSD-1",
            "tariffName": "General - Demand",
            "lseId": 2654,
            "lseName": "Florida Power & Light Co",
            "priorTariffId": 3253628,
            "tariffType": "ALTERNATIVE",
            "customerClass": "GENERAL",
            "customerCount": 98011,
            "customerLikelihood": null,
            "territoryId": 3004,
            "effectiveDate": "2016-04-01",
            "endDate": "2017-01-01",
            "timeZone": "US/Eastern",
            "billingPeriod": "MONTHLY",
            "currency": "USD",
            "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,DEMAND_BASED,MINIMUM",
            "chargePeriod": "MONTHLY",
            "hasTimeOfUseRates": false,
            "hasTieredRates": false,
            "hasContractedRates": false,
            "hasRateApplicability": false,
            "isActive": false
        }
    ]
}

From this information, you can determine that there are two tariff versions for the bill with a date range of 12/12/2016 to 1/13/2017. Therefore, when you run the calculation, you should split the usage inputs from (i) 12/12/2016 to 1/1/2017 and (ii) 1/1/2017 to 1/13/2017.

Does the Utility Pro-rate within a Billing Period?

In the instructions above, we recommend that you always set billingPeriod = true when matching a bill. By setting billing period to true, you indicate to the calculator that fixed charges and demand charges should be calculating as if the billing period range was exactly one month. This means that your fixed charge will be the same whether your billing period has 28 days or 32 days.

But not all utilities treat billing periods in this way. If you find that your fixed charges and demand charges are all off by the same percentage and the billing period is anything other than 30 days, try switching to billingPeriod = false.

As a final note, we know of at least one utility (PSEG-LI) that calculates demand charges using the number of hours in the billing period. Unfortunately they are not consistent about including the exact meter read times on their bills, so the final resolution of those charges can involve some guess work.

Billing Corrections and other Non-Electricity Charges

Sometimes individual sites will have additional, non-tariff charges included on their bill. These charges can include bill credits, installation charges, custom equipment charges and even individually-negotiated discounts. These can usually be identified on the bill as those charges that are neither clear meter charges nor charges driven by consumption (kWh) or demand (kW).

To include non-tariff charges in your calculations, we recommend that you use User Adjusted Rates, which allow you to add a custom rate to a calculation or to an account.

If your Bill Still Doesn’t Match?

If you are unable to match the calculation to the customer’s bill after calibrating your calculation request and re-running the calculation, please email us at support@genability.com with the calculation’s requestId as well as a redacted bill for our support team to investigate.

There’s nothing we love more than a puzzle, so don’t be afraid to send us one!