Octopus Energy API¶

Octopus Energy provides a REST API for customers and partner organisations to browse our energy products and tariffs as well as create new quotes and accounts.

API basics¶

Base URL¶

All API requests should use a base URL of: https://api.octopus.energy

Note, all API requests must be made over HTTPS.

Authentication¶

Authentication is required for most API requests. This is performed via HTTP Basic Auth.

Provide your API key as the basic auth username value. You do not need to provide a password, eg:

curl -u "$API_KEY:" https://api.octopus.energy/v1/accounts/

Note the colon after $API_KEY which prevents cURL from asking for a password.

Warning

Do not share your secret API keys with anyone.

Parameters¶

Datetimes¶

Some API end-points accept datetime strings as parameters. These should be passed in ISO 8601 format. Eg:

"2018-05-17T16:00:00+01:00"

If no timezone information is included, the “Europe/London” timezone will be assumed.

API end-points¶

Energy products¶

List products¶

Return a list of products that are visible to the authenticated organisation. This includes public products and those restricted to that organisation.

Request:

GET /v1/products/

Parameters:

is_variable: (boolean, optional) Show only variable products.
is_green: (boolean, optional) Show only green products.
is_tracker: (boolean, optional) Show only tracker products.
is_prepay: (boolean, optional) Show only pre-pay products.
is_business: (boolean, default: false) Show only business products.
available_at: (datetime, default: now) Show products available for new agreements on the give datetime. Defaults to current datetime, effectively showing products that are currently available.

Responses:

A 200 OK response with:

{
  "count": 108,
  "next": "https://api.octopus.energy/v1/products/?page=2",
  "previous": null,
  "results": [
    {
      "code": "VAR-17-01-11",
      "full_name": "Flexible Octopus January 2017 v1",
      "display_name": "Flexible Octopus",
      "description": "This great value 12 month fixed tariff guarantees…",
      "is_variable": true,
      "is_green": false,
      "is_tracker": false,
      "is_prepay": false,
      "is_business": false,
      "is_restricted": false,
      "term": 12,
      "available_from": "2017-05-05T05:37:27Z",
      "available_to": null,
      "links": [
        {
          "href": "https://api.octopus.energy/v1/products/VAR-17-01-11/",
          "method": "GET",
          "rel": "self"
        }
      ]
    }
  ]
}

Notes:

The key term is the number of months that a product lasts for if it is fixed length.

Retrieve a product¶

Retrieve the details of a product (including all its tariffs) for a particular point in time.

Request:

GET /v1/products/{product_code}/

Arguments:

product_code: The code of the product to be retrieved, for example VAR-17-01-11.

Parameters:

tariffs_active_at: (datetime, default: now) The point in time in which to show the active charges. Defaults to current datetime.

Responses:

A 200 OK response with:

{
  "code": "VAR-17-01-11",
  "full_name": "Flexible Octopus January 2017 v1",
  "display_name": "Flexible Octopus",
  "description": "This great value 12 month fixed tariff guarantees…",
  "is_variable": true,
  "is_green": false,
  "is_tracker": false,
  "is_prepay": false,
  "is_business": false,
  "is_restricted": false,
  "term": 12,
  "available_from": "2017-05-05T05:37:27Z",
  "available_to": null,
  "tariffs_active_at": "2017-05-05T05:37:27Z",
  "single_register_electricity_tariffs": {
    "_A": {
      "direct_debit_monthly": {
        "code": "E-1R-VAR-17-01-11-A",
        "standard_unit_rate_exc_vat": 10.85,
        "standard_unit_rate_inc_vat": 10.85,
        "standing_charge_exc_vat": 20.00,
        "standing_charge_inc_vat": 20.00,
        "online_discount_exc_vat": 0,
        "online_discount_inc_vat": 0,
        "dual_fuel_discount_exc_vat": 0,
        "dual_fuel_discount_inc_vat": 0,
        "exit_fees_exc_vat": 0,
        "exit_fees_inc_vat": 0,
        "links": [
          {
            "href": "https://api.octopus.energy/v1/products/VAR-17-01-11/electricity-tariffs/E-1R-VAR-17-01-11-A/standard-unit-rates/",
            "method": "GET",
            "rel": "standard_unit_rates"
          },
          {
            "href": "https://api.octopus.energy/v1/products/VAR-17-01-11/electricity-tariffs/E-1R-VAR-17-01-11-A/standing-charges/",
            "method": "GET",
            "rel": "standing_charges"
          }
        ]
      },
      "direct_debit_quarterly": {}
    },
    "_B": {}
  },
  "dual_register_electricity_tariffs": {},
  "single_register_gas_tariffs": {},
  "sample_quotes": {
    "_A": {
      "direct_debit_monthly": {
        "electricity_single_rate": {
          "annual_cost_inc_vat": 90000,
          "annual_cost_exc_vat": 85000
        },
        "electricity_dual_rate": {},
        "dual_fuel_single_rate": {},
        "dual_fuel_dual_rate": {}
      },
      "direct_debit_quarterly": {}
    },
    "_B": {}
  },
  "sample_consumption": {
    "electricity_single_rate": {
      "electricity_standard": 3100
    },
    "electricity_dual_rate": {
      "electricity_day": 2436,
      "electricity_night": 1764
    },
    "dual_fuel_single_rate": {
      "electricity_standard": 3100,
      "gas_standard": 12000
    },
    "dual_fuel_dual_rate": {
      "electricity_day": 2436,
      "electricity_night": 1764,
      "gas_standard": 12000
    }
  },
  "links": [
    {
      "href": "https://api.octopus.energy/v1/products/VAR-17-01-11/",
      "method": "GET",
      "rel": "self"
    }
  ]
}

Notes:

The key term is the number of months that a product lasts for if it is fixed length.

Each *_tariffs object will have up to 14 keys; one for each GSP. For each GSP the applicable tariffs are listed under their associated payment method, e.g. direct_debit_monthly.

Tariff charges are calculated for the tariffs_active_at datetime parameter.

The keys standard_unit_rate_* are listed in p/kWh (pence per kilowatt hour).

The keys standing_charge_* are listed in p/day (pence per day).

The keys annual_cost_* are listed in p (pence).

Historical charges can be browsed using the URLs contained under the key links.

List tariff charges¶

Return a list of unit rates and standing charges.

Request:

GET /v1/products/{product_code}/electricity-tariffs/{tariff_code}/standing-charges/

GET /v1/products/{product_code}/electricity-tariffs/{tariff_code}/standard-unit-rates/
GET /v1/products/{product_code}/electricity-tariffs/{tariff_code}/day-unit-rates/
GET /v1/products/{product_code}/electricity-tariffs/{tariff_code}/night-unit-rates/

GET /v1/products/{product_code}/gas-tariffs/{tariff_code}/standing-charges/
GET /v1/products/{product_code}/gas-tariffs/{tariff_code}/standard-unit-rates/

Arguments:

product_code: The code of the product to be retrieved, for example VAR-17-01-11.
tariff_code: The code of the tariff to be retrieved, for example E-1R-VAR-17-01-11-A.

Parameters:

period_from: (datetime, optional) Show charges active from the given datetime (inclusive). This parameter can be provided on its own.
period_to: (datetime, optional) Show charges active to the given datetime (exclusive). This parameter also requires providing the period_from parameter to create a range.

Response:

A 200 OK response with:

{
    "count": 48,
    "next": null,
    "previous": null,
    "results": [
        {
            "value_exc_vat": 11,
            "value_inc_vat": 11.55,
            "valid_from": "2018-05-16T22:30:00Z",
            "valid_to": "2018-05-16T23:00:00Z"
        },
        {
            "value_exc_vat": 10.6,
            "value_inc_vat": 11.13,
            "valid_from": "2018-05-16T22:00:00Z",
            "valid_to": "2018-05-16T22:30:00Z"
        },
    ]
}

Agile Octopus¶

If you’re using this API to query future unit-rates of the Agile Octopus product, note that day-ahead prices are normally created by 4pm in the Europe/London timezone. Furether, the market index used to calculate unit rates is based in the CET timezone (UTC+1) and so its “day” corresponds to 11pm to 11pm in UK time. Hence, if you query today’s unit rates before 4pm, you’ll get 46 results back rather than 48.

Example usage¶

For brevity, these examples use httpie and jq and a few environment variable to simplify the example commands:

$ export BASE_URL="https://api.octopus.energy"
$ export PRODUCT_CODE="AGILE-18-02-21"
$ export TARIFF_CODE="E-1R-$PRODUCT_CODE-C"
$ export TARIFF_URL="$BASE_URL/v1/products/$PRODUCT_CODE/electricity-tariffs/$TARIFF_CODE"

Fetch the latest unit rate charges:

$ http $TARIFF_URL/standard-unit-rates/ | jq '.results[:2]'
[
    {
        "value_exc_vat": 8.7,
        "value_inc_vat": 9.135,
        "valid_from": "2018-05-17T21:30:00Z",
        "valid_to": "2018-05-17T22:00:00Z"
    },
    {
        "value_exc_vat": 9.72,
        "value_inc_vat": 10.206,
        "valid_from": "2018-05-17T21:00:00Z",
        "valid_to": "2018-05-17T21:30:00Z"
    }
]

Print a CSV of charges for a given day:

$ http $TARIFF_URL/standard-unit-rates/ \
    period_from=="2018-05-16T00:00" period_to=="2018-05-17T00:00" | \
    jq -r '
        .results[] |
        [ .valid_from, .valid_to, (.value_inc_vat|tostring) ] |
        join (",")'
2018-05-16T22:30:00Z,2018-05-16T23:00:00Z,11.55
2018-05-16T22:00:00Z,2018-05-16T22:30:00Z,11.13
2018-05-16T21:30:00Z,2018-05-16T22:00:00Z,9.03
2018-05-16T21:00:00Z,2018-05-16T21:30:00Z,9.975
2018-05-16T20:30:00Z,2018-05-16T21:00:00Z,11.718
2018-05-16T20:00:00Z,2018-05-16T20:30:00Z,13.44
2018-05-16T19:30:00Z,2018-05-16T20:00:00Z,12.39
2018-05-16T19:00:00Z,2018-05-16T19:30:00Z,13.86
2018-05-16T18:30:00Z,2018-05-16T19:00:00Z,13.545
2018-05-16T18:00:00Z,2018-05-16T18:30:00Z,14.91
2018-05-16T17:30:00Z,2018-05-16T18:00:00Z,27.72
2018-05-16T17:00:00Z,2018-05-16T17:30:00Z,27.3
2018-05-16T16:30:00Z,2018-05-16T17:00:00Z,28.035
...

Convert prices into sentences:

$ http $TARIFF_URL/standard-unit-rates/ \
    period_from=="2018-05-16T00:00" period_to=="2018-05-17T00:00" | \
    jq -r '
        .results[] |
        "Price between \(.valid_from) and \(.valid_to) is \(.value_inc_vat) p/kWh"'
Price between 2018-05-16T22:30:00Z and 2018-05-16T23:00:00Z is 11.55 p/kWh
Price between 2018-05-16T22:00:00Z and 2018-05-16T22:30:00Z is 11.13 p/kWh
Price between 2018-05-16T21:30:00Z and 2018-05-16T22:00:00Z is 9.03 p/kWh
Price between 2018-05-16T21:00:00Z and 2018-05-16T21:30:00Z is 9.975 p/kWh
Price between 2018-05-16T20:30:00Z and 2018-05-16T21:00:00Z is 11.718 p/kWh
Price between 2018-05-16T20:00:00Z and 2018-05-16T20:30:00Z is 13.44 p/kWh
Price between 2018-05-16T19:30:00Z and 2018-05-16T20:00:00Z is 12.39 p/kWh
Price between 2018-05-16T19:00:00Z and 2018-05-16T19:30:00Z is 13.86 p/kWh
Price between 2018-05-16T18:30:00Z and 2018-05-16T19:00:00Z is 13.545 p/kWh
Price between 2018-05-16T18:00:00Z and 2018-05-16T18:30:00Z is 14.91 p/kWh
Price between 2018-05-16T17:30:00Z and 2018-05-16T18:00:00Z is 27.72 p/kWh
Price between 2018-05-16T17:00:00Z and 2018-05-16T17:30:00Z is 27.3 p/kWh
...

Print cheapest unit rate on a given day:

$ http $TARIFF_URL/standard-unit-rates/ \
    period_from=="2018-05-16T00:00" period_to=="2018-05-17T00:00" | \
    jq '.results| min_by('.value_inc_vat')'
{
    "value_exc_vat": 7.2,
    "value_inc_vat": 7.56,
    "valid_from": "2018-05-16T04:30:00Z",
    "valid_to": "2018-05-16T05:00:00Z"
}

Electricity meter-points¶

Retrieve a meter-point¶

Retrieve the details of a meter-point.

This endpoint can be used to get the GSP of a given meter-point.

Request:

GET /v1/electricity-meter-points/{mpan}/

Arguments:

mpan: The electricity meter-point’s MPAN.

Response:

A 200 OK response with:

{
    "gsp": "_H",
    "mpan": "2000024512368",
    "profile_class": 1
}

Consumption¶

List consumption for a meter¶

Return a list of kWh consumption values for half-hour periods for a given meter-point and meter.

Request:

GET /v1/electricity-meter-points/{mpan}/meters/{serial_number}/consumption/
GET /v1/gas-meter-points/{mprn}/meters/{serial_number}/consumption/

Arguments:

mpan / mprn: The electricity meter-point’s MPAN or gas meter-point’s MPRN.
serial_number: The meter’s serial number.

Parameters:

period_from: (datetime, optional) Show consumption from the given datetime (inclusive). This parameter can be provided on its own.
period_to: (datetime, optional) Show consumption to the given datetime (exclusive). This parameter also requires providing the period_from parameter to create a range.
page_size: (integer, optional) Page size of returned results. Default is 100, maximum is 25,000 to give a full year of half-hourly consumption details.
order_by: (string, optional) Ordering of results returned. Default is that results are returned in reverse order from latest available figure. Valid values: * ‘period’, to give results ordered forward. * ‘-period’, (default), to give results ordered from most recent backwards.
group_by: (string, optional) Grouping of consumption. Default is that consumption is returned in half-hour periods. Possible alternatives are: * ‘hour’ * ‘day’ * ‘week’ * ‘month’ * ‘quarter’

Response:

A 200 OK response with:

{
    "count": 48,
    "next": null,
    "previous": null,
    "results": [
        {
            "consumption": 0.063,
            "interval_start": "2018-05-19T23:00:00Z",
            "interval_end": "2018-05-19T23:30:00Z"
        },
        {
            "consumption": 0.071,
            "interval_start": "2018-05-19T22:30:00Z",
            "interval_end": "2018-05-19T23:00:00Z"
        }
    ]
}

Quotes¶

Create a quote¶

Warning

This endpoint is only available to partner organisations.

Request:

POST /v1/quotes/

Sample payload:

{
  "electricity_meter_points": [
    {
      "postcode": "BH24 4BP",
      "consumption_standard": 3100
    }
  ],
  "gas_meter_points": [
    {
      "postcode": "BH24 4BP",
      "consumption_standard": 12500
    }
  ],
  "product_codes": [
    "VAR-17-01-11"
  ]
}

Sample business products only payload:

{
  "electricity_meter_points": [
    {
      "postcode": "BH24 4BP",
      "consumption_standard": 3100,
      "mpan": "2000024512368"
    }
  ],
  "product_codes": [
    "VAR-17-01-11"
  ],
  "business_products_only": true
}

Arguments:

electricity_meter_points / gas_meter_points

Required. An array of object with the following members.

At least one electricity or gas meter-point must be included. A maximum of one electricity and one gas meter-point can included at this time. For all meter-points, at least one of gsp or postcode must be included. All meter-points must be based in the UK, excluding Northern Ireland. All meter-points must belong to the same gsp or postcode.

For an electricity meter-point, at least one of consumption_standard or a combination of consumption_day and consumption_night must be included.

For a gas meter-point, consumption_standard must be included.

gsp: The grid supply point.
postcode: The postcode of the property. You only need to provide this if you are unable to provide a gsp.
consumption_standard: The standard consumption of a single register electricity or gas meter-point.
consumption_day: The day consumption of a dual register electricity meter-point.
consumption_night: The night consumption of a dual register electricity meter-point.
has_smart_meter: Whether a smart meter is installed. The default is false.
mpan: The MPAN of the electricity meter-point, required when creating business quotes.

product_codes

Required. An array of Octopus Energy product codes to create quotes for.

business_products_only

Whether to create business quotes instead of domestic. The default is false. When set to true only a single electricity meter-point must be included with an associated mpan.

Responses:

A successful submission will receive a 201 Created response with:

{
  "code": "50b348fcf01c4a57a5cba10c6c424b4e",
  "gsp": "_H",
  "products": [
    {
      "code": "VAR-17-01-11",
      "full_name": "Flexible Octopus January 2017 v1",
      "display_name": "Flexible Octopus",
      "description": "This great value 12 month fixed tariff guarantees…",
      "monthly_amount": 7930,
      "annual_amount": 95159,
      "electricity_til": {
        "supplier": "Octopus Energy",
        "tariff_name": "Flexible Octopus February 2017 v1",
        "tariff_type": "Standard variable product",
        "tariff_code": "E-1R-VAR-17-01-11-H",
        "payment_method": "Monthly direct debit",
        "tariff_ends_on": "",
        "price_guaranteed_until": "",
        "exit_fees": 0,
        "additionals": "",
        "tcr": 15.85,
        "standing_charge": 18.9,
        "assumed_annual_consumption_day": null,
        "assumed_annual_consumption_night": null,
        "assumed_annual_consumption": 3100,
        "unit_rate_day": null,
        "unit_rate_night": null,
        "unit_rate": 13.629,
        "estimated_annual_cost": 49148,
        "annual_standing_charge": 6898.5
      },
      "gas_til": {
        "supplier": "Octopus Energy",
        "tariff_name": "Flexible Octopus February 2017 v1",
        "tariff_type": "Standard variable product",
        "tariff_code": "G-1R-VAR-17-01-11-H",
        "payment_method": "Monthly direct debit",
        "tariff_ends_on": "",
        "price_guaranteed_until": "",
        "exit_fees": 0,
        "additionals": "",
        "tcr": 3.68,
        "standing_charge": 18.9,
        "assumed_annual_consumption_day": null,
        "assumed_annual_consumption_night": null,
        "assumed_annual_consumption": 12500,
        "unit_rate_day": null,
        "unit_rate_night": null,
        "unit_rate": 3.129,
        "estimated_annual_cost": 46011,
        "annual_standing_charge": 6898.5
      }
    }
  ]
}

Any validation errors will receive a 400 Bad Request response detailing the errors.

Accounts¶

Create an account¶

Warning

This endpoint is only available to partner organisations.

Request:

POST /v1/accounts/

Sample payload:

{
  "reference": "12067-056785",
  "sold_at": "2017-07-28T14:30:00+01:00",
  "account_type": "DOMESTIC",
  "source": "INTERNET",
  "is_change_of_tenancy": false,
  "payment": {
    "method": "MONTHLY_DIRECT_DEBIT",
    "account_name": "Chris Johnson",
    "account_number": "12345678",
    "account_sort_code": "111111",
    "payment_day": 1
  },
  "billing_address": {
    "address_line_1": "87 Doveys Close",
    "address_line_2": "",
    "address_line_3": "",
    "town": "Ringwood",
    "county": "",
    "postcode": "BH24 4BP"
  },
  "users": [
    {
      "title": "Dr",
      "given_name": "Chris",
      "family_name": "Johnson",
      "date_of_birth": "1966-01-01",
      "email": "chris@example.com",
      "mobile": "07742628216",
      "landline": "02084459876",
      "opted_in_for_marketing": false
    }
  ],
  "electricity_meter_points": [
    {
      "tariff_code": "E-1R-VAR-17-01-11-A",
      "quote": {
        "annual_payment": 46576
      },
      "consumption_standard": 3100,
      "mpan": "2000024512368",
      "address": {
        "address_line_1": "87 Doveys Close",
        "address_line_2": "",
        "address_line_3": "",
        "town": "Ringwood",
        "county": "",
        "postcode": "BH24 4BP"
      },
      "meter_type": "CREDIT",
      "has_smart_meter": false,
      "current_supplier_name": "EON",
      "current_supplier_tariff": "EON-123"
    }
  ],
  "gas_meter_points": [
    {
      "tariff_code": "E-1R-VAR-17-01-11-A",
      "mprn": "3016362107",
      "consumption_standard": 12500,
      "quote": {
        "annual_payment": 44961
      }
    }
  ]
}

Arguments:

reference

Required. A unique partner reference up to 64 characters in length.

sold_at

Required. A datetime of when the account sale was made.

account_type

Required. One of DOMESTIC or BUSINESS.

source

Required. One of CALL_CENTRE_INBOUND, CALL_CENTRE_OUTBOUND, FACE_TO_FACE or INTERNET.

is_change_of_tenancy

Required. Whether this account is a change of tenancy at the property.

smart_meter_read_permission

One of MONTHLY, DAILY, HALF_HOURLY or DENIED. The default is HALF_HOURLY. This is the read permission frequency the occupier grants to meter readings from smart meters.

preferred_ssd

A preferred supply start date. Only include this field if the earliest possible supply start date is not preferred.

payment

Required. An object with the following members. The payment details are required when using the method MONTHLY_DIRECT_DEBIT. The MONTHLY_DIRECT_PAYMENT method is not available to all users.

method: Required. One of MONTHLY_DIRECT_DEBIT or MONTHLY_DIRECT_PAYMENT.
account_name: Conditional. The name associated with the bank account.
account_number: Conditional. The bank account number.
account_sort_code: Conditional. The bank account sort code.
payment_day: Conditional. The preferred day of the month for the payment request. Must be in the range of 1-28.

billing_address

Required. An object with the following members.

address_line_1: Required.
address_line_2: …
address_line_3: …
town: Required.
county: …
postcode: Required.

users

Required. An array of object with the following members.

A maximum of one user can included at this time. At least one of mobile or landline must be included.

title: …
given_name: Required.
family_name: Required.
date_of_birth: …
email: Required. Cannot be a email already in use for an Octopus Energy account.
mobile: …
landline: …
opted_in_for_marketing: Required.

electricity_meter_points / gas_meter_points

Required. An array of object with the following members.

At least one electricity or gas meter-point must be included. A maximum of two electricity and one gas meter-point can included at this time. All meter-points must be based in the UK, excluding Northern Ireland. All meter-points must belong to the same address.

For an electricity meter-point, at least one of mpan or address must be included. At least one of consumption_standard or a combination of consumption_day and consumption_night must be included.

For a gas meter-point, at least one of mprn or address must be included, as well as consumption_standard.

tariff_code

Required. The Octopus Energy tariff code. Must match an available tariff on the sold_at datetime for the authenticating partner.

quote

Required. An object with the following members.

annual_payment: Required. The estimated annual payment for this meter-point based on consumption. This value must be provided in pence.

consumption_standard

Required if standard tariff. The expected annual consumption in kWh.

consumption_day

…

consumption_night

…

mpan / mprn

…

address

An object with the following members.

address_line_1: Required.
address_line_2: …
address_line_3: …
town: Required.
county: …
postcode: Required.

meter_type

One of CREDIT or PREPAYMENT. The default is CREDIT.

has_smart_meter

Whether a smart meter is installed. The default is false.

current_supplier_name

…

current_supplier_tariff

…

To create business accounts, business details are also required.

{
  "account_type": "BUSINESS",
  "business": {
    "name": "Acme Corporation Limited",
    "number": "09263424",
    "business_type": "LIMITED",
    "is_ccl_exempt": false,
    "is_vat_exempt": false,
    "head_count": 25,
    "annual_turnover": 575000
  }
}

business

Required. An object with the following members.

name: Required. The name of the business.
number: The registered number of the business. This field is required for LIMITED businesses.
business_type: Required. One of SOLE_TRADER, LIMITED, PARTNERSHIP, or CHARITY.
is_ccl_exempt: Required. Whether the business is excempt from paying CCL (Climate Change Levy).
is_vat_exempt: Required. Whether the business is excempt from paying VAT.
head_count: The head count of the business, i.e. number of staff.
annual_turnover: The estimated annual turnover in pounds £ (GBP).

Responses:

A successful submission will receive a 201 Created response with:

{
  "number": "A-12341234"
}

Any validation errors will receive a 400 Bad Request response detailing the errors.

Table of Contents

Related Topics

Octopus Energy API¶

API basics¶

Base URL¶

Authentication¶

Parameters¶

Datetimes¶

API end-points¶

Energy products¶

List products¶

Retrieve a product¶

List tariff charges¶

Agile Octopus¶

Example usage¶

Electricity meter-points¶

Retrieve a meter-point¶

Consumption¶

List consumption for a meter¶

Quotes¶

Create a quote¶

Accounts¶

Create an account¶