Incentives are a special type of tariff in the Genability API. They represent programs offered by cities, states, utilities, and other entities that are designed to encourage the construction and use of energy saving technologies. They cover a wide range of technologies, especially solar or storage, and generally fall into a few broad categories:

  • Rebates - Cash payments. Usually the size of the rebate is related to the size of the project but, sometimes, they can just be fixed payments.
  • Bill credits - Similar to rebates, but applied directly to your energy bill.
  • Tax credits - Credits that can be applied to your local, state, or federal taxes, depending on the program.
  • Discounts - Subsidized prices for various project materials

This page outlines the data definitions and basic API operations for incentives. For a more in-depth guide in how to use this API, see the how-to.

Accessing Incentives

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

Data Definitions

An Incentive object consists of a set of properties describing how to calculate the incentive amount along with a list of applicabilities that specify what kinds of customers (and projects) the incentive is applicable to.

Incentive

The Incentive object has the following data structure.

Name Type Fields Description
incentiveId Integer   Genability ID of the incentive
masterIncentiveId Integer   “Master” ID for this incentive. Tracks a single incentive across multiple versions.
eligibility Eligibility   One of ELIGIBLE, INELIGIBLE, or COULD_BE_ELIGIBLE. If an incentive has any applicabilities that the user has not supplied any values for and none of the already-supplied applicabilities make the user INELIGIBLE, eligibility will be set to COULD_BE_ELIGIBLE and requiredData will be populated with the additional information that is required.
requiredData List of Applicability   If an incentive has formula-based applicabilities and the user does not provide all of the required information for that applicability, eligibility will be set to COULD_BE_ELIGIBLE and requiredData will be populated with the additional information that is required.
incentiveName String   The name of the incentive
projectType String   The type of project that this incentive applies to. For example, solarPv.
incentiveType String   The type of incentive. Can be a rebate, billCredit, taxCredit, or discount
state String   If applicable, the state where this incentive is available.
lseId Integer   The Genability ID of the LSE by whom the incentive is managed.
lseName String   The name of the LSE providing the incentive.
lseCode String   The short code for the LSE providing the incentive.
customerClass String   The class of customer that is eligible for this incentive.
startDate Date   The date when the incentive became or will become effective.
endDate Date   The date when the incentive expires.
isExhausted Boolean   true or false, depending on whether there are incentive funds remaining
jurisdiction String   The entity type that offers this incentive. In the case of a tax credit, this is also used to determine if the incentive applies to state or federal taxes.
quantityKey PropertyKey   The quantity by which to multiply the incentive rate.
rate Decimal   The rate by which to multiply the applicable quantity
rateUnit String   The type of rate for this incentive. Can be COST_PER_UNIT or PERCENTAGE.
quantityKeyCap String   The maximum quantity key (e.g. systemSizeAc) that is eligible for this incentive. For example, if quantityKey=systemSizeAc, the value of this field is 50, and the system size is 60, then the first 50 kW of the system is eligible for the incentive.
paymentCap Integer   Maximum dollar amount (in US) of this incentive.
percentCostCapKey PropertyKey   Quantity key that’s used to calculate the percent cost cap
percentCostCap Decimal   The maximum portion of the cost of the system cost that can be covered by the incentive
paymentDuration Integer   The duration of the incentive in years. Will be 1 if this is a one-time, up-front incentive
incentivePaidTo String   The party to whom the incentive is paid
projectTypeExclusive Boolean   Indicates if more than one incentive from this LSE/jurisdiction can be used for a customer for this projectType. True means only one incentive from the LSE/jurisdiction can be used. False means more than one incentive from the LSE/jurisdiction can be used.
summary String   Free text field describing the incentive. Designed to be used in a user interface as a general overview.
requirements String   Free text field describing the requirements for the incentive. Designed to be used in a user interface to give an overview of incentive’s requirements.
applicabilities List of Applicability   A list of applicabilities. Applicabilities are used to determine whether the customer is eligible for this incentive.

Applicability

The Applicability object has the following data structure. Applicabilities are used to determine whether a customer is eligible for an incentive. Customers must meet all applicabilities on an incentive in order to be eligible for that incentive.

Name Type Fields Description
applicabilityKey String   The name of variable that this applicability applies to. Examples include systemOwnership, azimuth, and tilt.
displayName String   A user-presentable name for this applicability.
description String   A user-presentable description of what this applicability represents.
requiredValue String   If there is a single value that is allowed for this applicability, it will show up here. For example, if systemOwnership requires host, it will be here.
minValue Decimal   For numeric applicabilities, the minimum allowed value.
maxValue Decimal   For numeric applicabilities, the maximum allowed value.
operator String   For formulaic applicabilities, the relationship that must be true for this applicability relative to its quantityKey. For example, estimatedFirstYearkWh might have a quantityKey of 110percentAnnualConsumption and an operator of <. This indicates that the estimated first year production of the solar power system must be less than 110% of the customer’s annual consumption.
quantityKey String   For formulaic applicabilities, a pointer to a PropertyKey that holds the formula defining this applicability.
choices List   For applicabilities with a fixed set of choices, the list of available choices.

Get a List of Incentives

This allows you to search for a set of incentives and get them back as a list of Incentive objects.

Resource URI

GET /rest/beta/incentives

Request Parameters

Name Type Description
projectType String Restrict the search to the given project type
incentiveType String Restrict the search to the given incentive type
defaultIncentives String Return the incentives that are available to most people, where “most people” is defined as those incentives that match the defaults for their respective applicabilities
applicabilities String Get incentives accepts an arbitrary list of key=value pairs representing inputs for the different applicability keys. Inputs do not cause the list of incentives to be filtered, but the eligibility status for each incentive is set depending on the applicability key values. For example, if a user inputs ?tilt=7&azimuth=180, then incentives that require a system with a tilt of 7 degrees and an azimuth of 180 degrees will be set to ELIGIBLE if those are the only applicabilities. If additional applicabilities exist, depending on key values, eligibility may also be INELIGIBLE or COULD_BE_ELIGIBLE. Available applicabilities for a given area are returned by Get Incentive Applicabilities. See the how-to guide for an example of how to use this endpoint.
customerClasses String RESIDENTIAL, GENERAL, or SPECIAL_USE. The type of customer
countryCode String Restrict the search to the given country
lseId Integer Restrict the search to the given LSE
state String Restrict the search to the given state
zipCode String Restrict the search to the given ZIP code
addressString String Restrict the search to the given addressString
effectiveOn Date Get only those incentives that are available as of the specified date.
fromDate Date Get incentives that are available after a certain date.
toDate Date Get incentives that are available before a certain date.
isExhausted Boolean Get incentives that are exhausted (or not)

Example

This example will get a list of solar rebates for ZIP code 94105 that were effective on October 26, 2015 and are not exhausted.

GET /rest/beta/incentives?zipCode=95448&projectType=solarPv&customerClasses=RESIDENTIAL&effectiveOn=2015-11-05&isExhausted=FALSE
{
  "status": "success",
  "count": 2,
  "type": "Incentive",
  "results": [
    {
      "incentiveId": 3158839,
      "masterIncentiveId": 3158839,
      "eligibility": "ELIGIBLE",
      "tariffCode": "None",
      "incentiveName": "Residential Renewable Energy Tax Credit",
      "lseId": 100281,
      "lseName": "State of California Incentives",
      "serviceType": "SOLAR_PV",
      "customerClass": "RESIDENTIAL",
      "startDate": "2006-01-01",
      "endDate": "2016-12-31",
      "isExhausted": false,
      "projectType": "solarPv",
      "incentiveType": "taxCredit",
      "rate": 30,
      "rateUnit": "PERCENTAGE",
      "documents": null,
      "jurisdiction": "federal",
      "quantityKey": {
        "keyName": "systemCostMinusIncentives",
        "displayName": "System Cost After Incentives",
        "description": "Cost of the solar system after incentives, rebates and tax credits"
      },
      "quantityKeyCap": null,
      "state": "CA",
      "percentCostCap": null,
      "percentCostCapKey": {
        "keyName": null
      },
      "paymentCap": 0,
      "paymentDuration": 1,
      "incentivePaidTo": "tenantOrOwner",
      "projectTypeExclusive": false,
      "applicabilities": [],
      "summary": "Established by The Energy Policy Act of 2005, the federal tax credit for residential energy property initially applied to solar-electric & solar water heating. Other key revisions included an 8-year extension of the credit to 12/31/2016; the ability to take the credit against the alternative minimum tax; & the removal of the $2000 credit limit for solar-electric beginning in 2009. The credit was further enhanced in February 2009 by The American Recovery & Reinvestment Act of 2009, which removed the maximum credit amount for all eligible technologies placed in service after 2008. A taxpayer may claim a credit of 30% of qualified expenditures for a system that serves a dwelling unit that is owned & used as a residence by the taxpayer. If the installation is at a new home, the \"placed in service\" date is the date of occupancy by the homeowner. Expenditures include labor costs for on-site preparation, assembly or original system installation, & for piping or wiring to interconnect a system to the home.",
      "requirements": "A taxpayer may claim a credit of 30% of qualified expenditures for a system that serves a dwelling unit that is owned & used as a residence by the taxpayer. Expenditures include labor costs for on-site preparation, assembly or original system installation, & for piping or wiring to interconnect a system to the home. The bill extends the 30% ITC for residential solar property for eight years through December 31, 2016."
   },

    /* more incentives */

]}

Get One Incentive

This endpoint retrieves a particular incentive by incentiveId.

Resource URI

GET /rest/beta/incentives/{incentiveId}

Request Parameters

Name Type Description
populateDetails Boolean Whether to include the applicabilities or not.
populateDocuments Boolean Whether to return link(s) to the relevant document(s)

Example

GET /rest/beta/incentives/3163702
{
  "status": "success",
  "count": 1,
  "type": "Incentive",
  "results": [
    {
      "incentiveId": 3163702,
      "masterIncentiveId": 3163702,
      "tariffCode": "None",
      "incentiveName": "Residential Solar Energy System Equipment Tax Credit",
      "lseId": 100287,
      "lseName": "State of New York Incentives",
      "serviceType": "SOLAR_PV",
      "customerClass": "RESIDENTIAL",
      "startDate": "2012-08-01",
      "endDate": null,
      "isExhausted": false,
      "projectType": "solarPv",
      "incentiveType": "taxCredit",
      "rate": 25,
      "rateUnit": "PERCENTAGE",
      "documents": null,
      "jurisdiction": "state",
      "quantityKey": {
        "keyName": "systemCost",
        "displayName": "System Cost",
        "description": "Cost of the solar system in USD. ",
        "quantityUnit": "USD"
      },
      "quantityKeyCap": null,
      "state": "NY",
      "percentCostCap": null,
      "percentCostCapKey": {
        "keyName": null
      },
      "paymentCap": 5000,
      "paymentDuration": 1,
      "incentivePaidTo": "tenantOrOwner",
      "projectTypeExclusive": false,
      "applicabilities": [
        {
          "applicabilityKey": "systemSizeDcW",
          "displayName": "System Size DC W",
          "description": "Size of the solar system in Watts DC",
          "maxValue": 25000,
          "quantityUnit": "W"
        }
      ],
      "summary": "Enacted in August 1997, this personal income tax credit originally applied to expenditures on solar-electric (PV) equipment used on residential property. The credit, equal to 25% percent of the cost of equipment and installation, was expanded in August 2005 to include solar-thermal equipment. The solar-thermal provisions apply to taxable years beginning on and after January 1, 2006. The credit is capped at $5,000 for solar-energy systems placed in service on or after September 1, 2006. In August 2012 the credit was amended yet again to allow it to be claimed for systems installed under lease or power purchase agreements (PPAs) of at least 10 years in length. For third-party owned systems, the residential homeowner may claim a tax credit in the amount of lease or PPA payments made during the taxable year, for up to 15 years.",
      "requirements": "Systems must be new and in compliance with all applicable performance and safety standards. Electricity generation systems must be grid connected. Systems must comply with the 25 kW capacity limit on residential. The solar energy system must use solar radiation to produce energy for heating, cooling, hot water, or electricity for residential use.  The system must also be installed and used at your principal residence in New York State."
    }
  ]
}

Get Incentive Applicabilities

Get a list of properties representing the universe of applicabilities, restricted by the specified parameters. This can be used by developers entering new markets in order to know exactly what data they’ll need to gather from their customers to in order to find and calculate incentives properly. This endpoint accepts many of the same parameters as Get Incentives.

Resource URI

GET /rest/beta/incentives/applicabilities

Request Parameters

Name Type Description
projectType String Restrict the search to the given project type
incentiveType String Restrict the search to the given incentive type
country String Restrict the search to the given country
lseId Integer Restrict the search to the given LSE
customerClasses String RESIDENTIAL, GENERAL, SPECIAL_USE. The type of customer
state String Restrict the search for applicabilities to the given state
zipCode String Restrict the search to the given ZIP code
addressString String Restrict the search to the given addressString
effectiveOn Date Get only those incentives that are available as of the specified date. Defaults to today’s date, restricting the list of applicabilities to only those on active incentives.
isExhausted Boolean Get incentives that are exhausted (or not). Defaults to false, restricting the list of applicabilities to only those on non-exhausted incentives.

Example

The following example request will retrieve all of the applicabilities that you might see in the state of California for solar incentives.

GET /rest/beta/incentives/applicabilities?zipCode=95448&projectType=solarPv&customerClasses=RESIDENTIAL
{
  "status": "success",
  "count": 2,
  "type": "IncentiveApplicability",
  "results": [
    {
      "applicabilityKey": "systemOwnership",
      "displayName": "System Ownership",
      "description": "If incentive requires the system to be owned by the Host or Third Party to qualify.  ",
      "choices": [
        {
          "displayValue": "Host",
          "value": "host",
          "dataValue": "host",
          "likelihood": null
        },
        {
          "displayValue": "Third Party",
          "value": "thirdParty",
          "dataValue": "thirdParty",
          "likelihood": null
        }
      ]
    },
    {
      "applicabilityKey": "systemSizeAcW",
      "displayName": "System Size AC W",
      "description": "Size of the solar system in Watts AC",
      "quantityUnit": "W"
    }
  ],
  "pageCount": 25,
  "pageStart": 0
}