Handle Taxes

Pass utility tax rates into calculations or set tax rates on an account so subsequent calculations and savings analyses include them.

Tax handling workflow

Determine whether you want to pass taxes into one calculation or save them on the account.
Confirm the tax source, ideally from the customer’s utility bill.
Add one rateInputs entry per tax rate when running a calculation.
Or save one or more TAX rates on the account tariff for future calculations.
Review returned cost items where chargeType is TAX.

Choose how to model taxes

Use case	Recommended approach
One-off calculation or temporary override	Pass tax rates in `rateInputs`.
Reuse the same customer tax rate in future calculations	Save tax rates on the account tariff.
Multiple jurisdictions apply	Add multiple `TAX` rates.
Customer may be exempt or partially exempt	Use the customer’s bill or confirmed exemption status before setting the rate.

Before you model utility taxes

Understand Arcadia’s tax handling policy

Our source of truth is the utility’s rate book documentation. We model any taxes that a utility publishes. We do not model taxes that are not listed in a utility’s rate book; many local and municipal taxes are not captured.

Distinguish utility tax from sales tax

Do not equate the sales tax that is applied to the customer’s purchase price, such as a solar system or battery, with the utility tax that is applied to their utility bill. In most cases, utility taxes are a separate tax rate that applies only to utility bills.

Account for unpublished utility tax rates

Unlike tariff rates that must be filed with the state utility commission, jurisdictions are not required to publish their utility tax rates or tax exemption rules. One resource lists the UUT rates within California. Not every municipality within California applies a Utility Users Tax.

Account for overlapping jurisdictions

Depending on the customer’s location, multiple jurisdictions may apply utility taxes, including State, County, City, School District, Irrigation District, and Special Economic Zone jurisdictions. You can set multiple tax rates on a single account to account for multiple jurisdictions.

Account for tax exemptions and reductions

For each jurisdiction that applies a utility tax, specific customers or customer types may be 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.

Determine whether tax applies to every rate

In our experience across thousands of bills, there are rare cases where the tax rate 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 before those charges are included in the total.

Use a customer bill as the most accurate tax source

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 a function of any number of jurisdictions and are not always applied as defined.

Pass 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 a specific rate dollar amount can be used. Optionally, you can set the rateName and rateGroup so the returned cost items can be broken out.

`rateUnit`	Use when	Example
`PERCENTAGE`	You know the tax rate percentage.	`0.075` for 7.5%.
`COST_PER_UNIT`	You know the exact tax dollar amount.	`18.29`.

To model multiple jurisdictions, add multiple rateInputs entries with chargeType set to "TAX".

Use this sample request for Account Cost Calculation:

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

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

In this response, note:

chargeType is TAX.
itemQuantity is the subtotal amount used to calculate the percentage.
rateAmount is the tax percentage.
cost is the calculated tax amount.

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

You can also pass the absolute value of the tax amount in place of the percentage by using "COST_PER_UNIT" as the "rateUnit".

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

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

Set 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.

Use this request:

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

Most account endpoints support both Arcadia-generated accountId paths and your providerAccountId paths. This guide uses providerAccountId for readability.

Either request should include something like this in the request body:

{  
   "masterTariffId":"522",  
   "serviceType":"ELECTRICITY",  
   "rates":[  
      {  
         "chargeType":"TAX",  
         "rateName":"Utility User's Tax",  
         "rateBands":[  
            {  
               "rateAmount":0.075,  
               "rateUnit":"PERCENTAGE"  
            }  
         ]  
      }  
   ]  
}

Whenever you run an Account Cost Calculation or Savings Analysis from now on, it will include the customer's tax rate in costs and savings. Account-level properties can help reduce a lot of boilerplate in the request objects and are helpful for static configurations that will be applied on every calculation run.

To model multiple jurisdictions on the account, save multiple TAX rates on the account tariff.