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

# Key concepts

> Users, locations, tariffs and devices, and how a device gets its price.

A user has locations, a location holds tariffs and devices, and a device prices against the tariffs at its location.

```mermaid actions={false} theme={"system"}
flowchart LR
    U["User"] --> L["Location"]
    L --> T["Tariffs"]
    L --> D["Devices"]
```

| Object | What it is |
| :- | :- |
| [User](/docs/energy-api/reference/users/retrieve.md) | The person who owns the devices, with one or more locations |
| [Location](/docs/energy-api/reference/locations/retrieve.md) | A supply address, with its postal address, timezone and currency |
| [Tariff](/docs/energy-api/reference/tariffs/retrieve.md) | One price component of the supply contract at a location. Flatpeak refreshes it, usually once a day |
| [Device](/docs/energy-api/reference/devices/retrieve.md) | A battery, charger, vehicle, heat pump or solar system. You read prices and costs per device |

The supplier is a property of the tariff, so there is no supplier endpoint.

## Tariffs

Connect the tariff once per location and every device there prices against it, including devices added later. A device that moves prices against the tariffs at its new location.

| Field | Values |
| :- | :- |
| `tariff_type` | `COMMODITY`: the electricity itself. `NON_COMMODITY`: grid fees and other delivery charges |
| `direction` | `IMPORT`: from the grid. `EXPORT`: to the grid |
| `connection_type` | How Connect found the tariff. See the table below |

| `connection_type` | How | Kept current |
| :- | :- | :- |
| `DIRECT` | The user logged in to their supplier | Yes |
| `LIBRARY` | The user picked a tariff from the Flatpeak library | Yes |
| `MARKET` | Follows the wholesale index for the address | Yes |
| `MANUAL` | Prices typed by the user or read from an [uploaded bill](/docs/energy-api/guides/tariffs/connect.md#uploading-a-bill) | No. Ask the user to reconnect when the contract changes |

### Device tariffs

A device tariff is a tariff with a `device_id`, for a device the supplier prices separately, such as a heat pump on a reduced grid-fee rate. Connect creates one when the tariff the user connects applies to one device only.

* For the same `tariff_type` and `direction`, it replaces the location tariff for that device; the two are never combined.
* It is bound to the device and location pair, so it stops applying when the device moves away and applies again if the device returns.
* Deleting the device or the location deletes it.
* Location costs exclude energy priced under a device tariff, so no kWh is counted twice.

## Prices

A price combines the tariffs that apply at a point in time: commodity plus non-commodity. Fixed charges that do not depend on consumption, such as standing charges, are not included. For each type and direction, a device resolves to one tariff: its device tariff if it has one, otherwise the location tariff. The [price audit](/docs/energy-api/reference/prices/audit-device.md) returns each component per interval.

## Device types

Set `device_type` when you [create the device](/docs/energy-api/reference/devices/create.md): `BATTERY_STORAGE`, `ELECTRIC_VEHICLE`, `EV_CHARGER`, `AIR_CONDITIONER`, `HEAT_PUMP`, `WATER_HEATER`, `PV_SYSTEM`, `POWER_GENERATOR` or `OTHER`. Connect uses it for the noun your users see: `BATTERY_STORAGE` reads "your battery".

The type is all a device needs. Add a `pv` capability block to a solar system so [price windows](/docs/energy-api/guides/tariffs/optimizations.md#solar-forecasts) carry its forecast.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.