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

# Price Resolution Guide

> The structure of a resolved price and how calendar time, session duration, and energy consumption combine to produce a final price.

## Structure of a resolved price

Every resolved price follows the same three-level shape:

```text theme={null}
Price Type
    └── Day
          └── Price slots
```

### Price type

The top-level key describes what the price is based on:

| Field                                       | Based on                                                                                    |
| ------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `kwh_price`                                 | Energy consumed                                                                             |
| `time_price_while_energy_flow`              | Time while the vehicle is charging                                                          |
| `time_price_while_no_energy_flow`           | Time while the vehicle is parked, not charging                                              |
| `session_time_price`                        | Applies across the whole session, regardless of energy-flow state                           |
| `session_fee`                               | One-off, not time- or energy-based                                                          |
| `starting_fee`                              | One-off, not time- or energy-based                                                          |
| `time_price`, `blocking_fee` *(deprecated)* | Superseded by the fields above; still present in some responses but should not be relied on |

### Day

Within a price type, prices are organized by day of week (`MONDAY`–`SUNDAY`). If the resolved schedule is identical across all seven days, it is represented once under `ALL` — this is a size optimization, not a different kind of tariff or a "default" price. Some tariffs may still list seven identical per-day entries instead of collapsing to `ALL`; consumer logic should handle both shapes.

All calendar values — day of week, `time_from`, `time_to` — are expressed in **the station's local timezone**, not the customer's and not UTC, and should be rendered as-is without conversion.

### Price slots

Each day contains one or more price slots, applicable over a `time_from`–`time_to` window (or the whole day, if unset):

| Field                                                                   | Description                               |
| ----------------------------------------------------------------------- | ----------------------------------------- |
| `date_from` / `date_to`                                                 | Validity period of the price              |
| `tax`                                                                   | Tax percentage applied                    |
| `net_prices`                                                            | Raw price tiers, excluding VAT            |
| `user_facing_prices`                                                    | Customer-facing price tiers, VAT included |
| `blocking_cap`                                                          | Maximum blocking fee for a transaction    |
| `net_price`, `user_facing_price`, `grace_period_minutes` *(deprecated)* | Superseded by the tier lists above        |

## Resolving a price during a session

Locating the correct price slots (by day and time-of-day) determines *which* price applies. A second, independent dimension determines *which tier within it* applies once a session is underway:

* **Calendar time** — determines the active price slot (day, `time_from`/`time_to`).
* **Session-relative time** — determines the active tier within that price slot, via `from_minute`/`to_minute` (duration) or `from_kwh`/`to_kwh` (energy), measured from the start of that session.

These two dimensions are independent: a session restriction is never a calendar boundary, and a calendar boundary is never reset by session state. Either bound in a tier may be `null`, meaning "no upper limit" — never "zero" or "not set." A restriction can in principle require both duration and energy bounds simultaneously, though this is uncommon in practice.

Energy and time-based prices are applied differently once a session starts: the applicable energy price is resolved once, at the start of charging, and used for the entire session; time-based pricing instead follows the calendar schedule as it unfolds, so a session spanning a slot-price boundary is billed against each slot in turn. This distinction exists because not all partners reliably send the session updates needed for continuously re-evaluated energy pricing.

Cost calculation is always performed against `net_prices` (unrounded, VAT-excluded), not `user_facing_prices` (rounded for display, typically to 2 decimals). A cost computed manually from `user_facing_prices` may differ slightly from the actual calculated cost due to this rounding — `user_facing_prices` should be treated as what to display, not what to calculate from.

## Points requiring care

A single applicable price is the intersection of three independent dimensions — price type, calendar time, and session-relative state — and all three must be resolved together; applying a duration or energy tier as if it were a calendar boundary produces a plausible but incorrect price. Other points worth noting:

* A constant calendar schedule can still combine with a highly tiered session structure — a resolved price is not guaranteed to be a flat value.
* `net_prices` and `user_facing_prices` differ in both tax treatment and unit (time-based prices are per-hour in `net_prices`, per-minute in `user_facing_prices`), not only in VAT. Example: 6 euro/hour excl. VAT -> 0.12 euro/min incl. VAT (20%)
* `to_minute: null` / `to_kwh: null` means unbounded; treating null as falsy can incorrectly drop the final tariff tier, where null typically indicates an unlimited upper bound. This can result in the most expensive tier of the tariff being omitted.

Recommended resolution order: price type → day (or `ALL`) → time-of-day price slot, in station-local time → session restriction tier (duration and/or energy) for the session in question.

## Examples

### Full example: constant schedule, tiered by session duration

A station that charges:

```text theme={null}
First 30 minutes: free
30–60 minutes: €0.20/minute
After 60 minutes: €0.40/minute
```

resolves to a constant calendar schedule (`ALL`) whose price slot holds the session tiers:

```python theme={null}
{
    "ALL": [
        {
            "time_from": None,
            "time_to": None,
            "user_facing_prices": [
                { "from_minute": 0,  "to_minute": 30,   "price": "0.00" },
                { "from_minute": 30, "to_minute": 60,   "price": "0.20" },
                { "from_minute": 60, "to_minute": None, "price": "0.40" }
            ],
            ...
        }
    ]
}
```

### Duration tier scoped to a specific day and time window

> "€0.45/min (after 60 min, 06:00–17:00)"

```python theme={null}
{
    "MONDAY": [
        {
            "time_from": "00:00",
            "time_to": "01:00",
            "user_facing_prices": [
                { "from_minute": 0, "to_minute": None, "price": "0.00" }
            ],
            ...
        },
        ...,
        {
            "time_from": "06:00",
            "time_to": "07:00",
            "user_facing_prices": [
                { "from_minute": 0,  "to_minute": 60,   "price": "0.00" },
                { "from_minute": 60, "to_minute": None, "price": "0.45" }
            ],
            ...
        },
        ...,
        {
            "time_from": "16:00",
            "time_to": "17:00",
            "user_facing_prices": [
                { "from_minute": 0,  "to_minute": 60,   "price": "0.00" },
                { "from_minute": 60, "to_minute": None, "price": "0.45" }
            ],
            ...
        },
        {
            "time_from": "17:00",
            "time_to": "18:00",
            "user_facing_prices": [
                { "from_minute": 0, "to_minute": None, "price": "0.00" }
            ],
            ...
        },
        ...
    ],
    ...,
    "SUNDAY": [
        ...
    ]
}
```