> ## 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. # Get customer-specific tariff details > Returns tariff pricing tied to a specific consumer's metering point. Use this when public tariff data is insufficient to determine correct pricing — for example, where a supplier's tariff varies in ways not resolvable from name and postcode alone. **Requirements:** 1. Caller must be a Registered TI User (RTI User). 2. The consumer must have granted consent to this RTI User for the specific MPXN via the OAuth 2.0 Authorisation Code flow. 3. The MPXN must be registered to the requested supplier. Suppliers validate RTI User status against the register at least once per day. Requests from unregistered parties or without active consent are rejected. ## OpenAPI ````yaml /tariff-interop/api/openapi-tariff.yaml get /v1/tariff/customer openapi: 3.1.0 info: title: Tariff Interoperability API version: 0.1.1.AE description: > The Tariff Interoperability (TI) API lets Energy Smart Appliances, optimisers, and third-party services access standardised electricity tariff pricing data directly from GB energy suppliers. It is defined under the Retail Energy Code (REC) and mandated by the Smart Secure Electricity Systems (SSES) Programme. ## Two tiers of access | Tier | Who can use it | Auth required | |------|---------------|---------------| | **Public Tariff Pricing Data** | Any TI User | None | | **Consumer Specific Tariff Information** | Registered TI Users (RTI Users) with active consumer consent | OAuth 2.0 | contact: name: Auth Energy email: contact@auth.energy license: name: | © 2025 Retail Energy Code Company Ltd v0.1.0. All modifications and improves published © 2026 Auth Energy Ltd url: https://auth.energy/ servers: - url: https://register.tariff.interop description: > Central TI Register hosted by RECCo. Serves the `/v1/suppliers` and `/v1/users` endpoints only. The `v1` path prefix identifies the API version. - url: https://example-supplier.co.uk description: > Placeholder for a TI Energy Supplier's own hosted API. Each supplier runs their own instance at a URL they register with RECCo — discover it from `GET /suppliers`. Serves all `/v1/tariff`, `/v1/consent`, `/v1/webhook`, `/v1/report`, and outbound webhook endpoints. security: [] tags: - name: Registry description: >- Discover active suppliers and registered third-party users. Served by the central RECCo register. No authentication required for public data. - name: Tariffs description: >- Retrieve tariff listings and full pricing detail from a specific supplier. No authentication required. - name: Consumer Tariffs description: >- Retrieve tariff data tied to a specific consumer metering point. Requires OAuth 2.0 and active consumer consent. - name: Consent description: >- Register and revoke consumer consent linking a metering point to an RTI User via the OAuth 2.0 Authorisation Code flow. - name: Webhooks description: >- Manage webhook endpoints and receive push notifications when tariff data or consent state changes. - name: Reporting description: >- Submit periodic performance assurance metrics to RECCo (supplier obligation). paths: /v1/tariff/customer: get: tags: - Consumer Tariffs summary: Get customer-specific tariff details description: > Returns tariff pricing tied to a specific consumer's metering point. Use this when public tariff data is insufficient to determine correct pricing — for example, where a supplier's tariff varies in ways not resolvable from name and postcode alone. **Requirements:** 1. Caller must be a Registered TI User (RTI User). 2. The consumer must have granted consent to this RTI User for the specific MPXN via the OAuth 2.0 Authorisation Code flow. 3. The MPXN must be registered to the requested supplier. Suppliers validate RTI User status against the register at least once per day. Requests from unregistered parties or without active consent are rejected. operationId: getConsumerTariff responses: '200': description: Consumer-specific tariff pricing detail. content: application/json: schema: type: object properties: data: type: array minItems: 1 items: $ref: '#/components/schemas/TariffDetail' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' security: - oauth2AuthCode: - tariff:read:consumer servers: - url: https://example-supplier.co.uk description: TI Energy Supplier API components: schemas: TariffDetail: type: object description: >- Full tariff pricing record including unit rates, standing charge, and validity windows. required: - tariff_id - name - tariff_type - fuel_type - last_modified properties: tariff_id: $ref: '#/components/schemas/TariffId' name: type: string maxLength: 200 description: Consumer-facing display name. example: Comfy Cucumber October 2026 description: type: string maxLength: 2000 description: Optional free-text description of the tariff. example: >- A flexible electricity tariff with half-hourly prices tracking the wholesale market. version: $ref: '#/components/schemas/TariffVersion' tariff_type: $ref: '#/components/schemas/TariffType' fuel_type: $ref: '#/components/schemas/FuelType' energy_flow: $ref: '#/components/schemas/EnergyFlow' payment_method: $ref: '#/components/schemas/PaymentMethod' meter_type: $ref: '#/components/schemas/MeterType' customer_type: $ref: '#/components/schemas/CustomerType' ldz_region: $ref: '#/components/schemas/LdzRegion' percentage_green: type: number format: float minimum: 0 maximum: 100 description: Percentage of supply from renewable sources. example: 27 standing_charge: type: string pattern: ^\d+\.\d{2,5}$ description: > Daily standing charge in GBP, excluding VAT. Fixed-precision decimal string with exactly 5 decimal places (e.g. `"0.62500"`). example: '0.62500' vat_included: type: boolean description: > Whether VAT is included in the `unit_price` and `standing_charge` values. When `false`, all prices are exclusive of VAT and `vat_rate` must be present. example: true vat_rate: type: integer minimum: 0 maximum: 100 description: > VAT rate as a whole-number percentage (e.g. `5` for 5%, `20` for 20%). Required when `vat_included` is `false`. Standard domestic electricity rate is 5%. example: 5 comments: type: string maxLength: 2000 description: >- Additional context affecting the price — e.g. pass-through costs or incentives. example: >- Includes a £50 joining incentive applied as a bill credit in month 1. valid_from: $ref: '#/components/schemas/Timestamp' description: When this tariff ID became effective. valid_to: $ref: '#/components/schemas/Timestamp' description: When this tariff ID expires or expired. sellable_from: $ref: '#/components/schemas/Timestamp' description: When this tariff became available for consumers to sign up to. sellable_to: $ref: '#/components/schemas/Timestamp' description: >- When this tariff ceased or will cease to be available to new consumers. last_modified: $ref: '#/components/schemas/Timestamp' description: When pricing data for this tariff was last updated. rates: type: array description: > Tariff rates defined by season, day of week, and time window. Follows the FlatPeak schedule structure. Each entry in the array represents a seasonal block scoped by month, date, day, and hour. items: $ref: '#/components/schemas/TariffScheduleEntry' TariffId: type: string format: uuid pattern: ^trf_[0-9a-f]{32}$ description: > Compact UUID generated by the supplier uniquely identifying a set of tariff pricing data prefixed with `trf_`. A single display name may map to multiple tariff IDs where a supplier prices differently by payment method or region. example: trf_a1b2c3d4e5f67890abcdef1234567890 TariffVersion: type: integer description: > The version of the tariff **NOTE: a new tariff should be issued if the prices or times change, version is only used for descriptive field corrections** example: 1 TariffType: type: string description: > Whether the tariff is static or dynamic. - **static** — rates in the schedule are fixed until the supplier pushes a `tariff.update` webhook event. - **dynamic** — rates change over time. RTI Users must re-fetch the schedule proactively using `valid_from` / `valid_to` on the tariff to know when to refresh. No `tariff.update` webhook events are sent for dynamic tariff rate changes. enum: - static - dynamic FuelType: type: string description: Whether the tariff applies to `electricity` or `gas`. enum: - electricity - gas example: electricity EnergyFlow: type: string description: >- Direction of energy flow — `import` into the property or `export` out of it. enum: - import - export example: import PaymentMethod: type: string description: Payment method this tariff variant applies to. enum: - direct_debit - non_direct_debit - prepayment MeterType: type: string description: > Meter configuration this tariff applies to. - **single_rate** — one unit rate applies at all times (standard credit meter). - **multi_rate** — two or more unit rates apply at different times (e.g. Economy 7). - **smart** — half-hourly read smart meter, required for dynamic tariffs. - **prepayment** — prepayment meter. enum: - single_rate - multi_rate - smart - prepayment example: smart CustomerType: type: string description: Whether this tariff is available to residential or business consumers. enum: - residential - business example: residential LdzRegion: type: string description: > Local Distribution Zone (LDZ) or Network Operator region code. Identifies the geographic pricing zone for this tariff. enum: - SC - 'NO' - NE - NWT - WMD - EM - EA - NT - SO - SE - WN - WW - SW example: SE Timestamp: type: string format: date-time description: ISO 8601 datetime with millisecond precision. example: '2026-11-01T10:00:00.000Z' TariffScheduleEntry: type: object description: > A seasonal block of the tariff schedule. Mirrors the FlatPeak schedule object structure. Each entry scopes rates by month, day-of-month, day-of-week, and time window. required: - days_and_hours properties: months: type: array description: > Months this schedule entry applies to. Use `["All"]` for year-round applicability, or specify individual months as three-letter abbreviations (`Jan`, `Feb`, `Mar`, `Apr`, `May`, `Jun`, `Jul`, `Aug`, `Sep`, `Oct`, `Nov`, `Dec`). items: type: string example: Oct example: - All dates: type: array description: > Day-of-month numbers (1–31) this entry applies to. Omit or use `[]` to mean all dates within the specified months. items: type: integer minimum: 1 maximum: 31 example: 1 example: - 1 days_and_hours: type: array description: Day-of-week and time-window groupings within this seasonal block. minItems: 1 items: $ref: '#/components/schemas/DaysAndHours' ErrorResponse: type: object required: - code - message properties: code: type: string description: Machine-readable error code. example: tariff_not_found message: type: string description: Human-readable error description. example: No tariff found for the given tariff_id and supplier MPID. details: type: string description: Additional context to help diagnose the issue. example: >- tariff_id a1b2c3d4-e5f6-7890-abcd-ef1234567890 does not exist for supplier SEBD. DaysAndHours: type: object description: A set of time windows scoped to specific days of the week. required: - days - hours properties: days: type: array description: > Days of the week this entry applies to. Use `["All"]` for every day, or any combination of `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, `Sun`. items: type: string example: Mon example: - Mon - Tue - Wed - Thu - Fri hours: type: array description: Time windows within the specified days. minItems: 1 items: $ref: '#/components/schemas/HourlyRate' HourlyRate: type: object description: A single time window with its associated unit rate. required: - valid_from - valid_to - rate properties: valid_from: $ref: '#/components/schemas/TimeOfDay' description: Start of this time window (inclusive), in `HH:MM:SS`. example: '07:00:00' valid_to: $ref: '#/components/schemas/TimeOfDay' description: End of this time window (exclusive), in `HH:MM:SS`. example: '16:00:00' rate: type: array description: Rate tiers within this time window. Most tariffs have a single tier. minItems: 1 items: $ref: '#/components/schemas/RateTier' TimeOfDay: type: string pattern: ^\d{2}:\d{2}:\d{2}$ description: Time in HH:MM:SS format. Used for static tariff rate window boundaries. example: '07:00:00' RateTier: type: object description: > A unit rate tier, optionally capped by a consumption threshold. Multiple tiers support block-rate tariffs where the unit price changes after a given volume. required: - unit_price properties: unit_price: type: string pattern: ^\d+\.\d{2,5}$ description: > Unit rate in GBP per kWh, excluding VAT. Stored and transmitted as a fixed-precision decimal string with exactly 5 decimal places to avoid floating-point rounding errors (e.g. `"0.24301"`). example: '0.24301' to_kwh: type: integer description: > Upper consumption threshold in kWh at which this rate tier applies. Omit on the final (or only) tier to indicate it applies to all remaining consumption. example: 30 responses: BadRequest: description: >- 400 — Request does not match the required format or references an out-of-scope tariff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: 401 — Missing or invalid authentication credentials. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: > 403 — Authenticated but not authorised. Common causes: caller is not a registered RTI User, or active consumer consent is not in place for the requested MPXN. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: >- 404 — The supplier MPID, tariff ID, or metering point does not exist or is not in scope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' TooManyRequests: description: >- 429 — Rate limit reached. Suppliers may suspend access above 10,000 req/s. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 30 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerError: description: 500 — Unexpected server error. Retry within the 72-hour buffer window. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: oauth2AuthCode: type: oauth2 description: > OAuth 2.0 Authorisation Code flow for RTI User authentication and consumer consent. Each supplier operates its own OAuth server. In production, substitute the placeholder host with the relevant `url` from the Supplier Register. OpenAPI does not permit URI templates in security scheme URLs, so a placeholder is used here. flows: authorizationCode: authorizationUrl: https://example-supplier.co.uk/oauth2/authorize tokenUrl: https://example-supplier.co.uk/oauth2/token scopes: tariff:read:consumer: Read consumer-specific tariff data for consented metering points. tariff:register: Register and revoke consumer consent relationships. tariff:webhook: Register and manage webhook endpoints. ````