Taxes

Overview

We collect rates that appear in utility tariff books. In most cases, tax rates are specific to the customer’s local municipality so they are not published by the utility. However, when you have a customer’s bill with taxes such as Sales Tax and Utility User’s Tax listed, you can incorporate the tax rates for the calculation by passing the tax rates in a request or by setting the tax rates on an account.

When you pass through a tax rate either in a calculation request or on an account, we will use the subtotal cost of the bill to calculate for the tax. If you have a Sales Tax of 4.5% set on an account and you pass a Sales Tax of 6.5% in a calculation request, the Sales Tax in the calculation request will override the tax set on the account and 6.5% will be used for the calculation.

Passing Tax Rates in a Request

Calculations can be performed with tax rate inputs. You will simply pass in the tax rate as a tariff 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 On-Demand Cost Calculation endpoint:

POST /rest/v1/ondemand/calculate
{
   "masterTariffId": 522,
   "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:

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

Setting Tax Rates on an Account

You can set tax rates in your account’s tariffs to incorporate a tax into a calculation such as Account Cost Calculation or Savings Analysis.

Here is an example:

PUT /rest/v1/accounts/{accountId}/tariffs
PUT /rest/v1/accounts/pid/{providerAccountId}/tariffs
{
   "masterTariffId":"522",
   "serviceType":"ELECTRICITY",
   "rates":[
      {
         "chargeType":"TAX",
         "rateName":"Utility User's Tax",
         "rateBands":[
            {
               "rateAmount":0.075,
               "rateUnit":"PERCENTAGE"
            }
         ]
      }
   ]
}