# List tariffs, sorted alphabetically by name.

List all the energy supplier tariffs known by the ev.energy system.
Use the `available_for_user_id` query parameter to narrow the list to only those relevant to a specific user and `supplier` query parameter to list only tariffs for a specific supplier.

Endpoint: GET /tariffs
Version: 2.0
Security: oauth2

## Query parameters:

  - `page` (number)
    The page number to return results for.

  - `page_size` (integer)
    Specify the number of results to return per page.

  - `expand` (array)
    Specify a url field to expand into a nested resource. The prices expansion requires tariff:prices:read scope.

  - `supplier_id` (string)
    The ID of the supplier to filter by.

  - `valid` (boolean)
    Filter by whether the tariff is currently open to new sign-ups (valid_from on or before today, and valid_until on or after today or unset). `true` returns only currently-available tariffs; `false` returns only superseded or not-yet-available ones. Omit to return all tariffs.

  - `gsp_group` (string)
    Filter by GB Grid Supply Point (DNO region) code, e.g. `_C` for London.

  - `available_for_user_id` (string)
    Filter to only return resources available in the user's region and program.

  - `include_optional` (string)
    Include optional tariffs.

## Header parameters:

  - `EvEnergy-Version` (number)
    Specify the version of this endpoint to use.

  - `EvEnergy-User` (string)
    If the client is authenticated using Client Credentials, setting EvEnergy-User to a valid user ID allows requests to be made as if you were directly authenticated as that user.

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique identifier for the given user.
    Example: tari01HN2NJ9NMRZBXT1H6FT9N7735

  - `url` (string, required)
    Example: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735

  - `supplier` (any, required)
    The energy company that supplies this tariff.

  - `supplier.id` (string, required)
    Unique identifier for the given user.
    Example: supl01HN2NJ9NMRZBXT1H6FT9N7735

  - `supplier.url` (string, required)
    Example: https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735

  - `supplier.name` (string, required)
    Example: Rivendell Renewables

  - `supplier.icon` (string | null, required)
    Example: https://cdn.example.com/rivendell_renewables.jpg

  - `supplier.highlighted` (boolean)
    A highlighted supplier is one that is often selected by users.

  - `name` (string, required)
    Example: Fangorn Biomass

  - `currency` (string, required)
    Example: GBP

  - `highlighted` (boolean)
    A highlighted tariff is one that is often selected by users.

  - `type` (string)
    Enum: "FLAT_RATE", "DUAL_RATE", "THREE_RATE", "DYNAMIC", "EXTERNALLY_MANAGED", "OTHER"

  - `daily_prices` (object)
    Information about the tariff's prices for different parts of the day.

  - `daily_prices.peak` (object, required)
    A single price for a certain time range.

  - `daily_prices.peak.price` (string)
    The price is in major currency units e.g. 0.10 means £0.10.
    Example: 0.10

  - `daily_prices.peak.times` (array)

  - `daily_prices.peak.times.start` (string)
    Example: 18:00:00

  - `daily_prices.peak.times.end` (string)
    Example: 00:00:00

  - `timezone_name` (string)
    Example: Europe/London

  - `price_chart_url` (string | null)
    The url of a website which can display a chart of prices for the tariff. This website is an external resource and is not affiliated with ev.energy.
    Example: https://www.example.com/

  - `gsp_group` (string | null)
    The GB Grid Supply Point (DNO region) the tariff applies to. Suppliers publish region-specific rates, so the same named tariff can appear once per region with differing prices; this field distinguishes them. `null` for tariffs that are not region-specific.
    Example: _C

  - `valid_from` (string)
    The date from which this tariff became available to new customers.
    Example: 2026-03-17

  - `valid_until` (string | null)
    The date after which this tariff is no longer available to new customers (it has been superseded). `null` if the tariff is still open to new sign-ups. Use the `valid` query parameter to filter the list to only currently-available tariffs.
    Example: 2027-03-17

  - `scheduler_tariff` (any)
    The tariff used by the scheduler for charge optimisation, which may differ from the billing tariff. Returns a URL by default, or null if not set. Expandable with ?expand=scheduler_tariff to return a TariffBase object (additional fields may be present beyond those listed here).

  - `scheduler_tariff.id` (string, required)

  - `scheduler_tariff.url` (string, required)

  - `scheduler_tariff.supplier` (string, required)

  - `scheduler_tariff.name` (string, required)

  - `scheduler_tariff.currency` (string, required)

## Response 400 fields (application/problem+json):

  - `type` (string)
    Example: https://api.ev.energy/v2/problems/example-problem/

  - `status` (number)
    Example: 400

  - `title` (string, required)
    Example: Short description

  - `detail` (string, required)
    Example: Long, more specific description.

  - `instance` (string)
    Example: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E

  - `notification` (object)
    Something that the user should be informed about.

  - `notification.id` (string, required)
    Unique identifier for the Notification
    Example: notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.url` (string, required)
    Example: https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.message_id` (string, required)
    Internal identifier for this notification type. E.g. 'ERR0023'

  - `notification.category` (string, required)
    Category of this notification type
    Enum: "ACTIONABLE", "SERVICE", "RETRY", "MARKETING", "INTERNAL"

  - `notification.event_time` (string, required)
    The timestamp of the event described by this notification

  - `notification.short_text_title` (string, required)
    Short title for the notification

  - `notification.short_text_body` (string, required)
    Short description of the event being notified

  - `notification.detail_page_title` (string, required)
    Title of a help page giving more information about this notification

  - `notification.detail_page_body` (string, required)
    Text of a help page giving more information about this notification

  - `notification.external_link` (string | null, required)
    URL of a web page giving further information about this notification

  - `notification.external_button_label` (string, required)
    Text to be displayed on a button leading to the external_link location

  - `notification.read_at` (string)
    When the user examined the contents of this notification

  - `notification.resolved_at` (string)
    When the problem associated with this notification was resolved

## Response 401 fields (application/problem+json):

  - `status` (number)
    Example: 401

  - `title` (string, required)
    Example: Unauthorized

  - `detail` (string, required)
    Example: Authentication credentials were not provided.

## Response 403 fields (application/problem+json):

  - `status` (number)
    Example: 403

  - `title` (string, required)
    Example: Forbidden

  - `detail` (string, required)
    Example: You do not have permission to perform this action.

## Response 404 fields (application/problem+json):

  - `status` (number)
    Example: 404

  - `title` (string, required)
    Example: Not found

  - `detail` (string, required)
    Example: Resource does not exist or cannot be accessed.

## Response 406 fields (application/problem+json):

  - `status` (number)
    Example: 406

  - `title` (string, required)
    Example: Not Acceptable

  - `detail` (string, required)
    Example: Could not satisfy the request Accept header.

## Response 429 fields (application/problem+json):

  - `type` (string)
    Example: https://api.ev.energy/v2/problems/example-problem/

  - `status` (number)
    Example: 400

  - `title` (string, required)
    Example: Short description

  - `detail` (string, required)
    Example: Long, more specific description.

  - `instance` (string)
    Example: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E

  - `notification` (object)
    Something that the user should be informed about.

  - `notification.id` (string, required)
    Unique identifier for the Notification
    Example: notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.url` (string, required)
    Example: https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.message_id` (string, required)
    Internal identifier for this notification type. E.g. 'ERR0023'

  - `notification.category` (string, required)
    Category of this notification type
    Enum: "ACTIONABLE", "SERVICE", "RETRY", "MARKETING", "INTERNAL"

  - `notification.event_time` (string, required)
    The timestamp of the event described by this notification

  - `notification.short_text_title` (string, required)
    Short title for the notification

  - `notification.short_text_body` (string, required)
    Short description of the event being notified

  - `notification.detail_page_title` (string, required)
    Title of a help page giving more information about this notification

  - `notification.detail_page_body` (string, required)
    Text of a help page giving more information about this notification

  - `notification.external_link` (string | null, required)
    URL of a web page giving further information about this notification

  - `notification.external_button_label` (string, required)
    Text to be displayed on a button leading to the external_link location

  - `notification.read_at` (string)
    When the user examined the contents of this notification

  - `notification.resolved_at` (string)
    When the problem associated with this notification was resolved