> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incentives.leap.energy/llms.txt
> Use this file to discover all available pages before exploring further.

# Incentives Guide

> Check which energy incentives a customer qualifies for through the Incentives Gateway.

Check which utility, market, and state incentives a customer qualifies for, and get a Connect URL the customer uses to apply.

## Base URL and authentication

`https://api.leap.energy` in production, `https://api.staging.leap.energy` in staging. Send your Leap API key as a **Bearer token**:

```http theme={"dark"}
Authorization: Bearer your_api_key_here
```

## Choosing an endpoint

All three return the same result. They differ in what you send and what they change.

|                     | **Look up**                      | **Refresh**                             | **Override**                                          |
| ------------------- | -------------------------------- | --------------------------------------- | ----------------------------------------------------- |
| Send                | Address, classification, devices | `reference_id`, plus whatever changed   | The same body as Look up                              |
| Customer            | Created if new                   | Must exist                              | Must exist                                            |
| Devices             | Establishes the device list      | Merged: add, update in place, or remove | **Replaced**: every installation on file is discarded |
| Address and utility | Resolved and stored              | Reused                                  | Re-resolved and rewritten from the request            |
| Customer details    | Stored                           | Merged                                  | Wiped, then set from the request                      |

Call Look up for a new customer. Call Refresh to re-run as-is, to add a device to a customer you already know, or to fill in details as you learn them: purchase price, install date, permit status. Call Override to correct the customer record itself, such as a wrong address or a teardown and reinstall.

<Warning>
  Override rebuilds the customer from the body you send. It re-geocodes the address, replaces the device set, and clears the customer details you supplied earlier. New `customer_device_id`s are issued, and the customer's Connect records are reset to match. The wipe can't be undone, so send a complete body rather than the fields that changed.
</Warning>

A lookup for a customer who already exists sets nothing new. If an entry names an installation that customer doesn't have, Leap skips it, returns it in `devices_ignored[]`, and still answers the eligibility question with a 200. Send new installations to Refresh instead, and check `devices_ignored[]` before you record a device as registered.

## Sending data as you learn it

Most of what a program asks about arrives after the first lookup. Send what you hold at quote time on Look up, and the rest on Refresh as you learn it. Both take the same keys, listed in the [Requirements reference](/setup-data-preferences).

Refresh merges what you send, stores it, and re-runs eligibility in the same call. Set `create_application` so the customer's application picks the values up too.

<Warning>
  Don't re-run a lookup on a `reference_id` you've already used. A second lookup drops installations the customer doesn't have into `devices_ignored[]`. When every entry drops, it returns a 200 with no programs and no `connect_url`. Add devices with Refresh instead.
</Warning>

## When a call is refused

Override is a pre-submission correction, so Leap refuses it rather than destroy something you didn't name. A `409` means nothing changed on either side: the address already belongs to another of your customers, an application has already been filed with a program administrator, the customer is shared across organizations, or the `reference_id` belongs to another partner. Read `error_code`, fix the cause, and retry.

A `502` needs more care. `GEOCODING_*` and `CONNECT_RESET_UNAVAILABLE` changed nothing and are safe to retry. The `CONNECT_RESET_FAILED`, `CONNECT_RESET_REJECTED`, and `CONNECT_RESET_REFUSED_AFTER_REBUILD` codes mean the rebuild committed here but Connect didn't confirm its side. Retrying can overlap a reset that is still running and destroy the customer's Connect records. Contact Leap support instead. Each response spells this out in its own description.

## Reading the results

Leap evaluates each device against each tier's requirements, and every requirement reports a status:

| Status      | `severity` | Meaning                                                                                                             |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------- |
| `COMPLETED` | `met`      | Satisfied.                                                                                                          |
| `FAILED`    | `blocking` | Not met. The device doesn't qualify for this tier.                                                                  |
| `IGNORED`   | `pending`  | Not knowable yet: the input doesn't exist until after the sale (install date, permit approval, new-equipment flag). |

`IGNORED` is not a rejection. A tier whose only open items are `IGNORED` still counts toward `incentive_summary`, so the summary is the customer's potential value, not a guaranteed amount. Supply the missing facts later and the checks resolve. To quote conservatively, sum only the tiers whose `device_results[].status` is `COMPLETED`.

Each check also carries `expected_values`, `actual_value`, and `operator`, which together say what the program wanted and what the customer has. Build a "what's missing" list from those rather than from parsing `reason`, which is display copy Leap rewords. The `code` says what kind of requirement it is: see [Eligibility check codes](/api-reference/incentives-lookups/eligibility-codes).

A tier identifies itself with `tier_id`, which is stable across relabeling. `tier_name` is the customer-facing label and is present only when the program's spec sets one, so show `tier_name` when it exists and key on `tier_id`.

Leap names utility, state, and market programs; your partner offer uses the name you set in the portal.

## How cost-based programs are priced

Some programs pay a percentage of what the customer spent. Others cap a flat amount at system cost. Either way, the amount depends on the cost Leap resolves for each device.

Two keys carry cost, both on the installation:

* `customer_device.purchase_price`: the equipment only.
* `customer_device.installation_cost`: labor, materials, and permits.

Send them in the `details` object on the matching `customer_devices[]` entry. When you don't, Leap estimates the cost from the device catalog and from typical costs for that category and state.

A percentage program pays `min(rate × cost, cap)`, summed over the devices that passed the tier. A flat rate capped at system cost pays the lesser of the two. A \$1,500 installation incentive against a \$1,000 actual cost pays \$1,000.

<Warning>
  Send both keys whenever you expect a cost-based program to price. An estimate is a fallback, not a guarantee: where Leap holds none, the cost resolves to zero and a program that would pay reads as ineligible.
</Warning>

See the [Requirements reference](/setup-data-preferences) for both keys and their value forms.