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:
- Use the Get Incentive Applicabilities endpoint to find what parameters we need to collect to correctly determine eligibility for the incentives.
- 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
= falsesystemSizeDcW
= 3000annualEstimatedSolarProduction
= 4500annualConsumption
= 5000isConEdCustomer
= 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 areutility
,state
, andfederal
, but there can be others.projectTypeExclusive
- Indicates if more than one incentive from this LSE can be used for a customer for thisprojectType
at this level ofjurisdiction
.
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 thequantityKey
. For example, if thequantityKey
has aquantityUnit
ofW
, then the rate will have units of dollars per Watt.rateUnit
- EitherCOST_PER_UNIT
orPERCENTAGE
. If thequantityKey
is in dollars, then this will bePERCENTAGE
. Otherwise, it will beCOST_PER_UNIT
.quantityKey
- The quantity by which to multiply the rate. In this case, thequantityKey
issystemSizeDcW
, indicating the incentive is based on the size of the PV system.quantityKeyCap
- The maximum portion of thequantityKey
value that is eligible for an incentive. In this case, thequantityKeyCap
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 tosystemCost
, 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. Ifrate
xquantityUnit
is higher than this value, then the actual incentive received will be equal topaymentCap
.paymentDuration
- The time period (in years) over which the incentive is paid. The total payment for the incentive will berate
xquantityUnit
xpaymentDuration
.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.
Updated about 18 hours ago