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

# Tariff Interoperability

> RECCo's tariff interoperability programme

<sub>First published: 25 March 2026 · Status: `PROPOSED`</sub>

<Note>
  In our process of understanding the current status of RECCo's Tariff Interoperability programme we've collated and updated their public reference material to get a better view.<p />
  This published spec is updated with our proposed changes, changes are © 2026 Auth Energy Ltd
</Note>

## What is it?

The Tariff Interoperability (TI) API is a GB government-mandated standard that requires electricity suppliers to publish their tariff pricing data via a consistent API. It is defined under the [Retail Energy Code (REC)](https://retailenergycode.co.uk/our-programmes/tariff-interoperability-project/) and driven by the Smart Secure Electricity Systems (SSES) Programme at DESNZ.

The goal is to let Energy Smart Appliances (EVs, heat pumps, batteries) and third-party optimisers automatically read tariff prices and optimise energy use — without consumers having to manually input their tariff details into every app and device.

## Two tiers of access

| Tier                                     | Who                                                          | Auth      |
| ---------------------------------------- | ------------------------------------------------------------ | --------- |
| **Public Tariff Pricing Data**           | Any TI User — no registration required                       | None      |
| **Consumer Specific Tariff Information** | Registered TI Users (RTI Users) with active consumer consent | OAuth 2.0 |

## Flow 1 — Discovering Public Tariff Data

Any application or device can retrieve public tariff pricing without authentication. The typical flow is two steps: look up the supplier's endpoint from the central register, then fetch their tariffs.

```mermaid theme={null}
sequenceDiagram
    actor User as TI User / ESA
    participant Reg as RECCo Register<br/>register.tariff.interop
    participant Sup as Energy Supplier<br/>energy.supplier

    User->>Reg: GET /v1/suppliers
    Reg-->>User: [{supplier_mpid, url, active}]
    Note over User: Identify target supplier MPID<br/>and their base URL

    User->>Sup: GET /v1/tariff/{mpid}
    Sup-->>User: [{tariff_id (uuid), name, last_modified}]
    Note over User: Pick the relevant tariff_id

    User->>Sup: GET /v1/tariff/{mpid}/{tariff_id}
    Sup-->>User: TariffDetail with schedule[]
    Note over User: Parse schedule →<br/>months / days / hours / rate tiers
```

***

## Flow 2 — Consumer Consent & Consumer-Specific Data

When public tariff data alone is insufficient to identify a consumer's exact pricing (e.g. their tariff varies by meter type or has a bespoke bolt-on), an RTI User can request consumer-specific data — but only with explicit consumer consent via OAuth 2.0.

<Warning>
  The consent mechanism described below (Option 1 — standalone OAuth) is under active review. RECCo is considering Option 2, which would defer consumer-specific access to the Consumer Consent Service (CCS) and deliver only public tariff data in Phase 1a. See the consent options section below.
</Warning>

```mermaid theme={null}
sequenceDiagram
    actor Consumer
    actor RTI as RTI User / Optimiser
    participant Sup as Energy Supplier<br/>energy.supplier
    participant Reg as RECCo Register<br/>register.tariff.interop

    RTI->>Reg: GET /v1/users (verify own active status)
    Reg-->>RTI: RTI User record confirmed active

    RTI->>Consumer: Initiate OAuth 2.0 Authorisation Code flow
    Consumer->>Sup: Authenticate & grant consent for MPXN
    Sup-->>RTI: Authorisation code

    RTI->>Sup: POST /v1/consent (bearer: auth code)
    Note over Sup: Resolves consumer identity<br/>from token, records consent
    Sup-->>RTI: {registration_id (uuid), [{mpxn, tariff_id}]}

    RTI->>Sup: GET /v1/tariff/{mpid}/{tariff_id}/consumer?mpxn=...
    Note over Sup: Validates RTI User active (daily check)<br/>Validates consent in place
    Sup-->>RTI: TariffDetail (consumer-specific)

    Consumer->>Sup: Revokes consent (via supplier mechanism)
    Sup->>RTI: Webhook → consent.revoked (within 1 working day)
    Note over RTI: Also possible: RTI User<br/>calls DELETE /v1/consent/{registration_id}<br/>Supplier must stop sharing within 60 min
```

***

## Flow 3 — Webhook Event Notifications

Once an RTI User has active consumer consent, the supplier pushes event notifications to the RTI User's registered webhook URL whenever something changes. RTI Users must verify the payload signature before acting.

```mermaid theme={null}
sequenceDiagram
    actor RTI as RTI User / Optimiser
    participant Sup as Energy Supplier<br/>energy.supplier

    RTI->>Sup: POST /v1/webhook {webhook_url}
    Sup-->>RTI: {webhook_id (uuid)}

    Note over Sup,RTI: Consumer has active consent — events begin flowing

    Sup-)RTI: POST {webhook_url}<br/>tariff.update — static tariff rate changed<br/>webhook-signature header for verification
    RTI-->>Sup: 200 OK

    Sup-)RTI: POST {webhook_url}<br/>tariff.change — consumer moved to new tariff
    RTI-->>Sup: 200 OK

    Sup-)RTI: POST {webhook_url}<br/>supplier.change — consumer switched supplier
    RTI-->>Sup: 200 OK

    Note over Sup: On non-2xx response:<br/>retry every 20s × 3, then hourly<br/>for up to 12 hours

    Sup-)RTI: POST {webhook_url}<br/>consent.revoked
    RTI-->>Sup: 200 OK
    Note over RTI: Stop requesting consumer data
```

<Info>
  Dynamic tariffs do **not** generate `tariff.update` events. RTI Users must poll proactively, using the `valid_from` / `valid_to` datetimes on rate windows to know when to refresh.
</Info>