HomeGuidesAPI ReferenceChangelog
Log In
Guides

Finding and Calculating Solar Incentives

Suggest Edits

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 incentives that are available

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 [Incentive Applicabilities][applicabilities] endpoint to find what parameters we need to collect to correctly determine eligibility for the incentives.
  2. Use the [Get Incentives][incentives] request along with the parameters we gathered in step (1) in order to actually 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 Applicabilities][applicabilities] endpoint comes in. Using this endpoint, we can see all of the possible applications that we may run into in 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, 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 what information we might need for incentives in that area:

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

This will return the following list of applicabilities:

{  
  "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 that we defined above, the values will be:

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

Get a List of Available Incentives

Request Parameters

Once we've gotten all of the data that we need, we're ready to search for incentives. We can use the data that we gathered above so the results of our search will show which incentives are eligible for the system that we've 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 a really long request! Let's break that down a little bit. The parameters can be split into three groups:

  • Parameters that we used on our search for applicabilities. Since we're looking for residential solar incentives in New York, it makes sense to keep all of those parameters.
  • Applicability parameters. Based on our applicabilities search, we knew that providing more information would 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.
  • Extra parameters for Get Incentives. 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 specify isExhausted=false and effectiveOn=2015-11-04 (the date that this how-to was written) to use the same behavior on Get Incentives.

Results

Once all of our parameters are set, we will get back a list of incentives. Each one will be tagged with an eligibility 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 needed in order 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 Eligibile 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 an 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 a number of 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)

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))

For a total incentive value of $1,800.

Updated 2 days ago