HomeGuidesAPI ReferenceChangelog
Log In
Guides
  1. Informational Resources

Find and Calculate Solar Incentives

Find eligible solar incentives, identify required applicability parameters, handle mutually exclusive incentives, and calculate incentive values.

Find eligible solar incentives, identify required applicability parameters, handle mutually exclusive incentives, and calculate incentive values.

Use the Solar Incentives API to find incentives that apply to a customer’s solar project and calculate the value of eligible incentives.

Access incentives

Confirm your account has permission to access incentives. If incentives are not enabled for your account, contact us to request access.

Find incentives

Use this two-step process to find the incentives that are available for your 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 gathered from step 1 to determine the eligibility status for each incentive.

Get the required applicabilities

The Arcadia API uses an applicability to determine a customer's eligibility for an incentive. An applicability is an eligibility input required by one or more incentives in a market. 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.

Use the Get Incentive Applicabilities endpoint to see the applicabilities you may encounter in a market. Use the response to collect the right information from your customer before you search for eligible incentives.

Use this example 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  
}

Use this information to drive your UI and gather the required data from your customer. For the system scenario above, the applicability fields and corresponding values are:

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

Get a list of available incentives

Request parameters

After you gather the required data, search for incentives that match the system constraints you defined. The Get Incentives endpoint accepts an arbitrary list of key=value pairs, one for each applicability you want to include in the eligibility check.

Use this 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

This request has three parameter groups:

Base parameters

These are the parameters from the initial applicability search. Because this example searches for residential solar incentives in New York, carry over projectType, zipCode, and customerClasses.

Applicability parameters

These are the customer and system values returned by the applicability search. In this example, the request provides values for every applicability, but that is not required. You can specify only some of them or none of them.

Supplemental parameters

By default, Get Incentive Applicabilities only looks for applicabilities that are relevant for active, non-exhausted incentives. Get Incentives, on the other hand, searches every incentive. Specify isExhausted=false and effectiveOn=YYYY-MM-DD to limit the results to active, non-exhausted incentives, similar to Get Incentive Applicabilities' native behavior.

Results

Once all 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 you 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"  
}]

This means the API needs more data before it can determine eligibility. In this request, we excluded the annualConsumption request parameter. annualConsumption was necessary to calculate the required value for certain applicabilities, including annualProduction. Because the API did not have all required values, it could not determine whether the request parameters were eligible for this incentive, so it set eligibility to COULD_BE_ELIGIBLE.

To resolve the COULD_BE_ELIGIBLE result, add the missing annualConsumption parameter back into the request.

Select 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, such as high price/short period versus lower price/longer period. In these cases, 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.

Calculate incentives

Calculate one of the incentives returned above. This example calculates the value for the third incentive, the Con Edison solar incentive.

In the Arcadia API, calculating the value of an incentive usually means multiplying the rate by the quantity indicated by the quantityKey, then applying any caps defined on the incentive. The following example shows 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

This example removes fields like summary and incentiveId that are not 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.

Do 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 = 3 kW (our system size)
  • 25,000 Watts = 25 kW (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))

This yields 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 about 5 hours ago