> ## 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.

# Context & Reasons

> Why Connect API resolves tariffs into a single price model instead of exposing protocol-specific data.

## What is price resolution?

Charging stations on the network are operated by many different parties, running different backend systems and different protocol versions. Even sources that claim to follow the same standard do not always represent a "price" the same way.

**Price resolution** is the process Connect API uses to convert a tariff from any supported source into one predictable, protocol-independent representation. Consumers of the API do not need to know which protocol or protocol version a tariff came from, or how closely the source implementation follows its own specification — only the resolved price structure, covered in the [Price Resolution Guide](./02-price-resolution-guide), needs to be understood.

## Why a single price field was not sufficient

A price typically passes through several systems before reaching an integration:

```text theme={null}
Station → CPO / backend → Protocol representation → Aggregator / eMSP → Application → Customer
```

At each step, tariff representations can differ in: which price components are supported, how session restrictions are interpreted, units (per hour vs. per minute), whether VAT is included, the timezone a schedule is expressed in, missing fields, and vendor-specific extensions outside any published specification. Tariffs built on the same standard (e.g. OCPI) do not behave identically once real stations are considered.

One example is `SESSION_TIME`, a time-based price tied to session length. It is not part of the official OCPI price components, but it is widely used by operators in production. A consumer that only recognizes official components would misinterpret or discard this data; a consumer that hard-codes support for it takes on an open-ended list of similar vendor-specific cases as they appear.

Historically, this interpretation was left to each consumer — every partner and internal service had to understand protocol-specific details and maintain its own handling of ambiguous or non-standard tariffs as new stations appeared. Two consumers reading the same source tariff could reasonably calculate two different prices, since the source data did not have one unambiguous meaning.

Earlier internal versions of price resolution reduced a tariff to a small set of flat fields (`net_price`, `user_facing_price`, `grace_period_minutes`). This was adequate while tariffs were genuinely flat, but did not extend to tariffs that depend on session state, such as:

```text theme={null}
0–30 minutes  → free
30–60 minutes → €0.40
60+ minutes   → €0.60
```

No single number represents this correctly; returning only one value discards the remaining tiers and forces the consumer to assume the rest of the tariff.

## What the resolved model does

Resolution moves interpretation to a single place — the resolution layer — before data reaches any consumer:

* **Non-standard but production-used components** (e.g. `SESSION_TIME`) are recognized and normalized rather than dropped or misread.
* **Multi-tier tariffs** are preserved in full, as a list of tiers, rather than collapsed into one value.
* **VAT and unit handling** are performed once, centrally, so all consumers see consistent `net_prices` and `user_facing_prices`.
* **Protocol compliance differences** are absorbed at the normalization boundary, so a technically non-compliant but production-used tariff still resolves correctly.

The result is a single contract that partners and internal services build against, rather than each needing to account for the full variability of the charging ecosystem.