Handle Taxes

Genability does not collect local utility tax rates but we do make them easy to incorporate these taxes into your calculations. Before we discuss how to incorporate taxes in the Genability Switch API, here are some important things to understand about taxes on utility bills.

Utility Tax is not Sales Tax

It is important to not equate the sales tax that is applied to the customer’s purchase price (solar system, battery etc.) to the utility tax that is applied to their utility bill. In the overwhelming majority of cases, utility taxes are a separate tax rate that applies only to utility bills.

Utility Tax rates are not Filed with Utility Commissions

Unlike tariff rates that must be filed with the state utility commission, jurisdictions are not required to publish their utility rates or tax exemption rules. The good news is there is a good site that lists the UUT rates within California. As you will note, not every municipality within California applies a Utility Users Tax.

Overlapping Jurisdictions

Depending on the customer’s location, there are multiple jurisdiction that may apply utility taxes: State, County, City, School District, Irrigation District, Special Economic Zone etc. We allow you to set multiple tax rates on a single account to account for multiple jurisdictions for this case.

Tax Exemptions/Reductions

For each jurisdiction that applies a utility tax, there is a chance that specific customer or customer types maybe eligible for tax exemptions or reductions. In our work with one utility in California we discovered that 60% of customers in one city qualified as exempt from the posted UUT rate.

Is Tax Applied to Every Rate

In our experience across thousands of bills, there are rarely cases where the tax rate only applies to only a portion of the bill. When this has been identified, we flag that portion of the rate as “AFTER_TAX” so that the taxes are applied prior to the inclusion of those charges in the total.

There is only one 100% Accurate Source for Taxes – A Customer Bill

As a rule when including taxes in your calculations, we recommend capturing the tax rate whenever the end user is most likely to have a utility bill to reference. Unlike electricity tariffs which are well-defined by the utility and approved by the utility commission, tax rates are the function of any number of jurisdictions and are not always applied as defined.

Passing Tax Rates into a Calculation

To perform a calculation with a tax rate, pass your tax rate(s) as a rate input using the chargeType set to "TAX". Tax rates are calculated using the subtotal from the calculated amount. Either a rate percentage or specific rate dollar amount can be used. Optionally, you can set the rateName and rateGroup so the returned cost items can be broken out.

Here is a sample request for the Account Cost Calculator:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
   "fromDateTime": "2016-06-15T00:00:00-07:00",
   "toDateTime": "2016-07-15T00:00:00-07:00",
   "billingPeriod": true,
   "propertyInputs":[
    {
         "keyName":"consumption",
         "dataValue":1000
    }],
   "rateInputs":[
    {
         "rateGroupName":"Taxes",
         "rateName":"Utility Users Tax",
         "chargeType":"TAX",
         "rateBands":[
            {
               "rateAmount": 0.075,
               "rateUnit":"PERCENTAGE"
            }]
    }]
}

Here is a snippet of the response where the item quantity reflects the subtotal amount:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "tariffRateId": 0,
  "rateSequenceNumber": 10000,
  "rateGroupName": "Taxes",
  "rateName": "Utility User's Tax",
  "fromDateTime": "2016-06-15T00:00:00-07:00",
  "toDateTime": "2016-07-15T00:00:00-07:00",
  "quantityKey": "percentage",
  "rateType": "PERCENTAGE",
  "rateAmount": 0.075,
  "itemQuantity": 243.92856,
  "cost": 18.294642,
  "chargeType": "TAX"
}

You can also able to pass the absolute value of the TAX amount in lieu of the percentage by using “COST_PER_UNIT” as the “rateUnit”.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
   "fromDateTime": "2016-06-15T00:00:00-07:00",
   "toDateTime": "2016-07-15T00:00:00-07:00",
   "billingPeriod": true,
   "propertyInputs":[
    {
         "keyName":"consumption",
         "dataValue":1000
    }],
   "rateInputs":[
    {
         "rateGroupName":"Taxes",
         "rateName":"Utility Users Tax",
         "chargeType":"TAX",
         "rateBands":[
            {
               "rateAmount": 18.29,
               "rateUnit":"COST_PER_UNIT"
            }]
    }]
}

In the response, the item quantity reflects the subtotal amount and the rate amount will be the percentage computed based on the absolute tax amount passed in the call.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "tariffRateId": 0,
  "rateSequenceNumber": 10000,
  "rateGroupName": "Taxes",
  "rateName": "Utility User's Tax",
  "fromDateTime": "2016-06-15T00:00:00-07:00",
  "toDateTime": "2016-07-15T00:00:00-07:00",
  "quantityKey": "percentage",
  "rateType": "PERCENTAGE",
  "rateAmount": 0.075,
  "itemQuantity": 243.92856,
  "cost": 18.29,
  "chargeType": "TAX"
}

Setting Tax Rates on an Account

You will likely want to set the tax rate on the account for use in subsequent calculations such as Account Cost Calculation or Savings Analysis.

Here is an example:

PUT /rest/v1/accounts/pid/{providerAccountId}/tariffs

… or if using our Genability Account ID …

PUT /rest/v1/accounts/{accountId}/tariffs

Either of the above should have something like this in the request body:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
   "masterTariffId":"522",
   "serviceType":"ELECTRICITY",
   "rates":[
      {
         "chargeType":"TAX",
         "rateName":"Utility User's Tax",
         "rateBands":[
            {
               "rateAmount":0.075,
               "rateUnit":"PERCENTAGE"
            }
         ]
      }
   ]
}

Thats it! Whenever you run a Savings Analysis or Account Cost Calculation from now on it will include the customers tax rate in costs and savings.