Skip to content
/
Retrieve a tariff

Retrieve a tariff

Request

Retrieve details for a single, specific tariff.

Security
oauth2(Required scopes: tariff:read)
Path
tariff_idstringtari[A-Z\d]{26}required

The ID of the specific tariff to retrieve.

Example:tari01HN2NJ9NMRZBXT1H6FT9N7735
Query
expandArray of strings

Specify a url field to expand into a nested resource. The prices expansion requires tariff:prices:read scope.

Items Enum:"supplier""scheduler_tariff""prices"
available_for_user_idstringuser[A-Z\d]{26}

Filter to only return resources available in the user's region and program.

Example:available_for_user_id=user01HN2NJ9NMRZBXT1H6FT9N7735
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value:2
curl -i -X GET \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735?expand=supplier&available_for_user_id=user01HN2NJ9NMRZBXT1H6FT9N7735' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Return a single Tariff.

Headers
EvEnergy-Versionnumber

Indicates the version of the API that generated this response. If EvEnergy-Version was not specified in the request, this will be your OAuth application's default version.

Value:2
X-RateLimit-Limitnumber

The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

Default:1000
X-RateLimit-Remainingnumber

The number of requests remaining until this client's rate limit is reached.

Default:999
RetryAfternumber

The number of seconds until this client's requests will not be rate limited.

Default:3600
Bodyapplication/json
current_priceinteger or null

The price of the tariff at the current time, given in the smallest unit of the currency of the tariff. For example, 10 means 10 pence.

Example:10
pricesstring or Array of objects or nullread-only
One of:

Link to prices endpoint by default. When expanded with ?expand=prices, returns the past 24 hours of prices. Requires tariff:prices:read scope.

string (uri)read-only
idstringtari[A-Z\d]{26}read-onlyrequired

Unique identifier for the given user.

Example:"tari01HN2NJ9NMRZBXT1H6FT9N7735"
urlstring, (uri)required
Example:"https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735"
supplierstring or Supplier (object)required
One of:

The energy company that supplies this tariff.

string (uri)
namestringrequired
Example:"Fangorn Biomass"
currencystringrequired
Example:"GBP"
highlightedboolean

A highlighted tariff is one that is often selected by users.

typeany
Enum:"FLAT_RATE""DUAL_RATE""THREE_RATE""DYNAMIC""EXTERNALLY_MANAGED""OTHER"
daily_pricesobject, [ 1 .. 3 ] properties(DailyPrices)

The times returned here are localised to the timezone the tariff is in. The timezone is returned in timezone_name.

timezone_namestring
Example:"Europe/London"
price_chart_urlstring or 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_groupstring or 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_fromstring, (date)

The date from which this tariff became available to new customers.

Example:"2026-03-17"
valid_untilstring or null, (date)

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_tariffstring or object or null
One of:

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

string (uri)
Response
{
  "id": "tari01HN2NJ9NMRZBXT1H6FT9N7735",
  "url": "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735",
  "supplier": "https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735",
  "name": "Fangorn Biomass",
  "currency": "GBP",
  "daily_prices": {
    "peak": { … },
    "mid_peak": { … },
    "off_peak": { … }
  },
  "scheduler_tariff": "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7835",
  "current_price": 10,
  "prices": "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735/prices"
}