Run an Account Cost Calculation to Match a Bill

Use the Account Cost Calculation API to reproduce a customer’s utility bill, compare the result, and calibrate calculation inputs.

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

Bill match workflow

1. Confirm the account has the correct utility and tariff.
2. Set the bill date range using the bill’s start (fromDateTime) and end (toDateTime) dates.
3. Add usage values from the bill as propertyInputs.
4. Add taxes or non-tariff charges if needed via user-adjusted rate objects.
5. Set billingPeriod and minimums to true.
6. Request enough detail with groupBy, detailLevel, and fields.
7. Compare the calculated total to the bill total.
8. Calibrate the request and rerun until the result is within your tolerance.
   1. Rate criteria adjustments and TOU period designations are good examples during this step.

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 doing them in chronological order. Once you have a good understanding of the specific rate criteria values for your customer, you can set these values on the Account to make this process more efficient for future requests.

Select the correct tariff

Run the calculation against the right tariff. See Select the Right Utility and Tariff, then come back here.

Make the bill match calculation request

The following example uses Account Cost Calculation with input parameters that allow us to match a bill.

POST /rest/v1/accounts/pid/{providerAccountId}/calculate/

{
    "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",
    "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"
                }]
        }]
}

The following table explains the example request:

Pass 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, use it in your account cost calculation to get the best match accuracy.

For each usage input, create an object in 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. When bills cross two tariff versions, the utility may have a date range for each tariff version.

Pass a tax rate

To include the customer’s tax rate, 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 Handle Taxes.

Pass other billing properties

You will need to pass rate criteria properties (such as the connection type) 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 about confirming rate criteria properties, we show you how to double-check the results to refine these values. You can also read Improving Calculation Accuracy with Rate Criteria Properties for more details on this important step.

Request the appropriate level of detail

1. groupBy - At what 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 Calculation Details and Grouping guide provides more detail on alternate options.

Compare the result to the bill

After the calculation returns, compare the calculated response to the values on the bill.

Calibrate your calculation request

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. Calibrate your Calculate call so you can rerun the calculation. The sections below highlight common issues that can prevent an exact bill match.

toDateTime is exclusive. The calculation covers the range from fromDateTime up to, but not including, toDateTime. If you pass a date without a time, such as 2026-05-01, the time defaults to midnight (T00:00:00) in the time zone of the masterTariffId.

Confirm the 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, Arcadia provides as much information as possible to help you select the correct tariff.

Confirm the date range

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 different utilities follow different rules. This is important because the 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.

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, Arcadia 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, add a day to your date range when running a calculation.

Confirm rate criteria properties

Review which rate criteria properties were defaulted. Most commercial and industrial tariffs can vary their pricing either based on the customer’s physical attributes, such as the voltage at which the site connects to the grid (connectionType), or optional programs in which the customer has enrolled, such as PG&E’s CARE program. If you do not specify these settings in your calculation, Arcadia 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 Arcadia 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). This response snippet has been shortened to show the relevant assumptions:

{  
    "keyName": "hasCAEnergySurchargeExemption",  
    "displayName": "Has Energy Surcharge Exemption",  
    "description": "Exemptions for CA Energy Surcharge apply to the following: Federal Agencies. American National Red Cross facilities. Energy consumed on Indian reservations. 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, read Improving Calculation Accuracy with Rate Criteria Properties.

Add contracted rates in deregulated markets

Is this a deregulated market with Contracted Rates? By default, Arcadia 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, read Contracted Rates in Deregulated Markets.

Check whether usage data is 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 the billing period crosses a season boundary, rates are updated in the middle of the billing period, or 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 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 Account Cost Calculation

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/accounts/pid/{providerAccountId}/calculate/

{  
    "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 that two tariff versions are used in the calculation because the assumptions section includes two tariffIds:

{  
    "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 from 12/12/2016 to 1/1/2017, and the second tariff version (tariffId of 3273719) was used from 1/1/2017 to 1/13/2017.

(B) Use the Account 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/v1/accounts/{accountId}/tariffs?effectiveOn=2016-12-12
GET /rest/v1/accounts/pid/{providerAccountId}/tariffs?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:

{  
    "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.

Check whether the utility prorates within a billing period

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

However, 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 guesswork.

Add billing corrections and 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 using User-Adjusted Rates, which allows 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 rerunning the calculation, email us at [email protected] for our support team to investigate.

Include:

• The calculation requestId
• A redacted copy of the bill
  • Please avoid sending any PII via support requests
• The expected bill total
• The calculated total returned by the API
• Any known tariff or rate criteria values