HomeGuidesAPI ReferenceChangelog
Log In
Guides
Start typing to search…

Finding and Calculating Solar Incentives

In the Arcadia API, incentives are similar to tariffs, but different. This How-To will show you how to:

  • Find the incentives that are applicable to your customers.
  • Calculate the value of the available incentives.

Accessing Incentives

In order to access incentives, you'll need special permissions on your account. Please contact us to find out more.

Finding Incentives

We'll use a two-step process to find the incentives that are available for our customers:

  1. Use the Get Incentive Applicabilities endpoint to find what parameters we need to collect to correctly determine eligibility for the incentives.
  2. Use the Get Solar Incentives endpoint along with the parameters we gathered from step (1) to determine the eligibility status for each incentive.

Get the Required Applicabilities

The Arcadia API uses the notion of an applicability to determine a customer's eligibility for a particular incentive. All incentives in the database have a list of these applicabilities, each of which represents a particular requirement for the incentive in question. For example, some incentives may require that the tilt and azimuth of your PV system fall within certain ranges. Others may require that the system not be owned by a third party. For each new market, these requirements will be different.

This is where the Get Incentive Applicabilities endpoint comes in. Using this endpoint, we can see all of the possible applications we may encounter within a new market. With this information, we'll be able to easily search for incentives that are eligible for our customers.

As an example, let's say we have the following system:

  • Residential customers consuming 5,000 kWh per year
  • Located in New York, NY
  • 3 kW system, producing 4,500 kWh per year
  • South facing (180 degrees), tilted at 25 degrees

Since this system is located in New York, we can use the following request to determine what information we might need for incentives in that area:

GET /rest/v1/incentives/applicabilities?projectType=solarPv&zipCode=10001&customerClasses=RESIDENTIAL

This request returns the following applicability list:

{  
  "status": "success",  
  "count": 5,  
  "type": "IncentiveApplicability",  
  "results": [  
    {  
      "applicabilityKey": "annualConsumption",  
      "displayName": "Annual Consumption ",  
      "description": "Annual Consumption by customer",  
      "quantityUnit": "kWh"  
    },  
    {  
      "applicabilityKey": "annualEstimatedSolarProduction",  
      "displayName": "Annual Estimated Solar Production",  
      "description": "How many kWh the solar system is estimated to produce in the first year. ",  
      "quantityUnit": "kWh"  
    },  
    {  
      "applicabilityKey": "isConEdCustomer",  
      "displayName": "Consolidated Edison Customer",  
      "description": "Is the applicant a Consolidated Edison customer?"  
    },  
    {  
      "applicabilityKey": "isLowIncome",  
      "displayName": "Low Income Customer",  
      "description": "Is the customer considered low income by the LSE. "  
    },  
    {  
      "applicabilityKey": "systemSizeDcW",  
      "displayName": "System Size DC W",  
      "description": "Size of the solar system in Watts DC",  
      "quantityUnit": "W"  
    }  
  ],  
  "pageStart": 0,  
  "pageCount": 25  
}

This information can be used to drive your UI and help you gather the required data from your customer. For the system scenario that we defined above, the applicability fields and corresponding values will be:

  • isLowIncome = false
  • systemSizeDcW = 3000
  • annualEstimatedSolarProduction = 4500
  • annualConsumption = 5000
  • isConEdCustomer = true

Get a List of Available Incentives

Request Parameters

After we gather all of the data we need, we're ready to search for incentives. We can use the compiled list above to guide our search, resulting in incentives that are eligible for the system constraints that we have defined. The Get Incentives endpoint will accept an arbitrary list of key=value pairs, one for each of the applicabilities that we found above.

For our system, we'll use the following request:

GET /rest/v1/incentives?zipCode=10001&isExhausted=false&effectiveOn=2015-11-04&isLowIncome=false&systemSizeDcW=3000&annualEstimatedSolarProduction=4500&annualConsumption=5000&projectType=solarPv&customerClasses=RESIDENTIAL&isConEdCustomer=true

That's quite a long request, let's break it down a little bit! The parameters can be split into three groups:

Base Parameters

These are the parameters we used in our initial applicability search. Since we're looking for residential solar incentives in New York, it makes sense to carry these parameters over.

Applicability parameters

Based on our applicability search, we knew that providing more information would help clarify which incentives in the list of available incentives are eligible. In this example, we're providing values for every applicability, but that's not required. You can specify only some (or none) of them.

Supplemental parameters

By default, Get Incentive Applicabilities will only look for applicabilities that are relevant for active, non-exhausted incentives. Get Incentives, on the other hand, will search for every incentive. We can specify the isExhausted=false and effectiveOn=YYYY-MM-DD fields to limit the results to active, non-exhausted incentives, similar to Get Incentive Applicabilities native behavior.

Results

Once all of our parameters are set, a list of incentives will be returned. Each incentive will be tagged with an eligibility value of ELIGIBLE , INELIGIBLE or COULD_BE_ELIGIBLE depending on whether the parameters that we sent in meet that incentive's requirements.

Three incentives come back as ELIGIBLE:

  • Residential Solar Tax Credit
  • Residential Renewable Energy Tax Credit
  • NYSERDA NY-SUN Residential Solar PV Incentive Con Edison - Block 5

And one comes back as INELIGIBLE:

  • NYSERDA NY-SUN Residential Solar PV Incentive Con Edison (Low-Income) - Block 5

Missing Formula Variables

What if we had used the following request instead?

GET /rest/v1/incentives?zipCode=10001&isExhausted=false&effectiveOn=2015-11-04&isLowIncome=false&systemSizeDcW=3000&annualEstimatedSolarProduction=4500&projectType=solarPv&customerClasses=RESIDENTIAL&isConEdCustomer=true

Now the incentive 'NYSERDA NY-SUN Residential Solar PV Incentive Con Edison - Block 5' has some new values:

"eligibility": "COULD_BE_ELIGIBLE",  
"requiredData": [  
{  
  "applicabilityKey": "annualConsumption",  
  "displayName": "Annual Consumption ",  
  "description": "Annual Consumption by customer",  
  "quantityUnit": "kWh"  
}]

What does this mean? In our new request, we've excluded the annualConsumption request parameter. It turns out that annualConsumption was necessary to calculate the required value for certain applicabilities, namely annualProduction. Because it didn't have all of the required values, the API was not able to determine whether the request parameters were eligible for this incentive, so it set the eligibility value to COULD_BE_ELIGIBLE.

To get rid of this error message, add the annualConsumption parameter back into the request.

Selecting from Multiple Eligible Incentives in the Same Jurisdiction

Some jurisdictions offer solar customers multiple solar incentives to choose from, but require the customer to select only one. This is common when there is a tradeoff between the value of the incentive and its payment period (high price/short period vs. lower price/longer period). In these cases, you will need to either require your customer to choose between eligible incentives or select a default option for them.

You can identify this scenario by referencing two parameters returned with the incentive:

  • jurisdiction - The jurisdictional level of this incentive. The most common values are utility, state, and federal, but there can be others.
  • projectTypeExclusive - Indicates if more than one incentive from this LSE can be used for a customer for this projectType at this level of jurisdiction.

In the third incentive returned above, the jurisdiction = state and projectTypeExclusive = true. This means that if the customer selects this incentive, they are ineligible for any other incentive with jurisdiction = state.

Calculating Incentives

Let's calculate one of the incentives returned above. We'll calculate the value for the third one -- the Con Edison solar incentive.

In the Arcadia API, calculating the value of an incentive is easy. In general, you can just multiply the rate by the quantity indicated by the quantityKey, with certain caps depending on the definition of a particular incentive. Let's take a look at the important fields of the NYSERDA NY-SUN Residential Solar PV Incentive Con Edison - Block 5 incentive:

{  
    "incentiveName": "NYSERDA NY-SUN Residential Solar PV Incentive Con Edison - Block 5",  
    "lseId": 100287,  
    "lseName": "State of New York Incentives",  
    "lseCode": "NY",  
    "serviceType": "SOLAR_PV",  
    "customerClass": "RESIDENTIAL",  
    "privacy": "PUBLIC",  
    "startDate": "2015-10-19",  
    "endDate": null,  
    "isExhausted": false,  
    "projectType": "solarPv",  
    "incentiveType": "rebate",  
    "rate": 0.6,  
    "jurisdiction": "state",  
    "quantityKey": {  
        "keyName": "systemSizeDcW",  
        "displayName": "System Size DC W",  
        "dataType": null,  
        "quantityUnit": "W"  
    },  
    "state": "NY",  
    "percentCostCapKey": {  
        "keyName": null,  
        "dataType": null  
    },  
    "rateUnit": "COST_PER_UNIT",  
    "quantityKeyCap": "25000",  
    "paymentCap": 0,  
    "percentCostCap": null,  
    "paymentDuration": 1,  
    "incentivePaidTo": "contractor",  
    "projectTypeExclusive": true,  
}

Important Fields

We've removed several fields like summary and incentiveId that aren't relevant to the calculation. To calculate an incentive, the most important fields are:

  • rate - The dollars per unit of the incentive. The unit is specified by the quantityKey. For example, if the quantityKey has a quantityUnit of W, then the rate will have units of dollars per Watt.
  • rateUnit - Either COST_PER_UNIT or PERCENTAGE. If the quantityKey is in dollars, then this will be PERCENTAGE. Otherwise, it will be COST_PER_UNIT.
  • quantityKey - The quantity by which to multiply the rate. In this case, the quantityKey is systemSizeDcW, indicating the incentive is based on the size of the PV system.
  • quantityKeyCap - The maximum portion of the quantityKey value that is eligible for an incentive. In this case, the quantityKeyCap is 25,000 (25 kW). If the system was actually 30 kW, only the first 25 kW would be eligible.
  • percentCostCapKey - Sometimes, the total incentive can't be more than some percentage of the cost of some portion of the system. If that is the case, then this field will indicate which value is the limiting one. For example, if this field was set to systemCost, then the limiting value would be the cost of the PV system.
  • percentCostCap - The allowable cost offset percentage for this incentive. There will be a decimal value between 0 and 1.
  • paymentCap - The maximum possible payment for this incentive. If rate x quantityUnit is higher than this value, then the actual incentive received will be equal to paymentCap.
  • paymentDuration - The time period (in years) over which the incentive is paid. The total payment for the incentive will be rate x quantityUnit x paymentDuration.
  • incentivePaidTo - The entity to whom the incentive is paid. In this case, it is paid to the contractor instead of the homeowner.

Doing the Calculation

The formula for calculating an incentive is:

    min(rate * min(quantityKey, quantityKeyCap), paymentCap, percentCostCap * percentCostCapKey)

In this case, that would translate to:

    min(0.6 * min(3000, 25000), null, null * null)
  • 3000 Watts = 3kW (Our system size)
  • 25,000 Watts = 25kW (Our incentive sizing cap)

Any time a cap or limit is null, that indicates that the limit does not apply. For this incentive, that means that the paymentCap and percentCostCap fields do not apply, reducing our formula to just:

    min(0.6 * min(3000, 25000))

Yielding a total incentive value of $1,800.00 as shown below:

rate: 0.6
quantityUnit: 3000
paymentDuration: 1

Total Incentive Payment = ((0.6 * 3000) * 1) = $1,800.00

Updated 3 months ago