Octopus Energy APIs¶

REST API¶

Octopus Energy provides a REST API for customers and partner organisations to interact with our platform. Amongst other things, it provides functionality for:

Browsing energy products, tariffs and their charges.
Retrieving details about a UK electricity meter-point.
Browsing the half-hourly consumption of an electricity of gas meter.
Determining the grid-supply-point (GSP) for a UK postcode.
Creating a quote.
Creating a account.

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 some API end-points. 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.

If you are an Octopus Energy customer, you can generate an API key from your online dashboard.

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:00Z"

We strongly recommend that timezone information is included on all datetime parameters. If no timezone information is included, the “Europe/London” timezone will be assumed and results may vary between GMT and British Summer Time.

API end-points¶

Energy products¶

List products¶

Return a list of energy products.

By default, results will be public energy products but if the authenticated organisations will also see products available to their organisation.

Authentication: public and authenticated.

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 given datetime. Defaults to current datetime, effectively showing products that are currently available.

Response:

A 200 OK response of form:

{
  "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,
      "brand": "OCTOPUS_ENERGY",
      "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,
  "brand": "OCTOPUS_ENERGY",
  "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 up to the given datetime (exclusive). You must also provide the period_from parameter in order to create a range.
page_size (int, optional): Page size of returned results. Default is 100, maximum is 1,500 to give up to a month of half-hourly prices.

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. Further, 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": 5,
        "value_inc_vat": 5.25,
        "valid_from": "2020-05-06T21:30:00Z",
        "valid_to": "2020-05-06T22:00:00Z"
    },
    {
        "value_exc_vat": 6.2,
        "value_inc_vat": 6.51,
        "valid_from": "2020-05-06T21:00:00Z",
        "valid_to": "2020-05-06T21:30:00Z"
    }
]

Print a CSV of charges for a given day:

$ http $TARIFF_URL/standard-unit-rates/ \
    period_from=="2020-02-12T00:00Z" period_to=="2020-02-13T00:00Z" | \
    jq -r '
        .results[] |
        [ .valid_from, .valid_to, (.value_inc_vat|tostring) ] |
        join (",")'
2020-02-12T23:30:00Z,2020-02-13T00:00:00Z,6.153
2020-02-12T23:00:00Z,2020-02-12T23:30:00Z,6.93
2020-02-12T22:30:00Z,2020-02-12T23:00:00Z,6.804
2020-02-12T22:00:00Z,2020-02-12T22:30:00Z,7.308
2020-02-12T21:30:00Z,2020-02-12T22:00:00Z,7.35
2020-02-12T21:00:00Z,2020-02-12T21:30:00Z,7.35
2020-02-12T20:30:00Z,2020-02-12T21:00:00Z,7.35
2020-02-12T20:00:00Z,2020-02-12T20:30:00Z,8.4
2020-02-12T19:30:00Z,2020-02-12T20:00:00Z,9.45
2020-02-12T19:00:00Z,2020-02-12T19:30:00Z,10.668
2020-02-12T18:30:00Z,2020-02-12T19:00:00Z,24.36
2020-02-12T18:00:00Z,2020-02-12T18:30:00Z,25.41
2020-02-12T17:30:00Z,2020-02-12T18:00:00Z,24.15
...

Convert prices into sentences:

$ http $TARIFF_URL/standard-unit-rates/ \
    period_from=="2020-02-12T00:00Z" period_to=="2020-02-13T00:00Z" | \
    jq -r '
        .results[] |
        "Price between \(.valid_from) and \(.valid_to) is \(.value_inc_vat) p/kWh"'
Price between 2020-02-12T23:30:00Z and 2020-02-13T00:00:00Z is 6.153 p/kWh
Price between 2020-02-12T23:00:00Z and 2020-02-12T23:30:00Z is 6.93 p/kWh
Price between 2020-02-12T22:30:00Z and 2020-02-12T23:00:00Z is 6.804 p/kWh
Price between 2020-02-12T22:00:00Z and 2020-02-12T22:30:00Z is 7.308 p/kWh
Price between 2020-02-12T21:30:00Z and 2020-02-12T22:00:00Z is 7.35 p/kWh
Price between 2020-02-12T21:00:00Z and 2020-02-12T21:30:00Z is 7.35 p/kWh
Price between 2020-02-12T20:30:00Z and 2020-02-12T21:00:00Z is 7.35 p/kWh
Price between 2020-02-12T20:00:00Z and 2020-02-12T20:30:00Z is 8.4 p/kWh
Price between 2020-02-12T19:30:00Z and 2020-02-12T20:00:00Z is 9.45 p/kWh
Price between 2020-02-12T19:00:00Z and 2020-02-12T19:30:00Z is 10.668 p/kWh
Price between 2020-02-12T18:30:00Z and 2020-02-12T19:00:00Z is 24.36 p/kWh
Price between 2020-02-12T18:00:00Z and 2020-02-12T18:30:00Z is 25.41 p/kWh
...

Print cheapest unit rate on a given day:

$ http $TARIFF_URL/standard-unit-rates/ \
    period_from=="2020-02-12T00:00Z" period_to=="2020-02-13T00:00Z" | \
    jq '.results| min_by('.value_inc_vat')'
{
    "value_exc_vat": 2,
    "value_inc_vat": 2.1,
    "valid_from": "2020-02-12T03:30:00Z",
    "valid_to": "2020-02-12T04: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 consumption values for half-hour periods for a given meter-point and meter.

Unit of measurement:

Electricity meters: kWh
SMETS1 Secure gas meters: kWh
SMETS2 gas meters: m^3

Warning

Half-hourly consumption data is only available for smart meters. Requests for consumption data for non-smart meters will return an empty response payload.

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 (int, 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"
        }
    ]
}

Industry¶

List grid supply points¶

Return a list of GSP objects, optionally filtered by postcode:

Authentication: public

Request:

GET /v1/industry/grid-supply-points/

Parameters:

postcode (string, optional): A postcode to filter on.

Response:

A 200 OK response with a list of GSP objects:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "group_id": "_A"
        },
    ]
}

Note, if we’re unable to map the passed postcode to a GSP, an empty list will be returned.

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": [
    {
      "id": 4122828,
      "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. The error response payload will take the same field structure as the request payload, eg:

{
    "product_codes": [
        "The following product codes are invalid: a-invalid-code."
    ]
}

Accounts¶

Create an account¶

Warning

This endpoint is only available to partner organisations.

This end-point allows an account to be created.

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,
      "psr": {
        "requires_signup": 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": "G-1R-VAR-17-01-11-A",
      "mprn": "3016362107",
      "consumption_standard": 12500,
      "quote": {
        "annual_payment": 44961
      }
    }
  ]
}

Parameters:

reference (string, max 64 chars, required)

A unique partner reference.

sold_at (string, required)

A datetime of when the account sale was made.

account_type (string, required)

One of DOMESTIC or BUSINESS.

brand_code (string, optional)

A code to specify the account should be for a particular brand. This is only required when creating an account in an instance with multiple brands and for which the requested brand is not the default brand of that instance.

source (string, required)

One of CALL_CENTRE_INBOUND, CALL_CENTRE_OUTBOUND, FACE_TO_FACE or INTERNET.

is_change_of_tenancy (string, required)

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

smart_meter_read_permission (string, required)

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 (string, optional)

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

payment (string, 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 (string, required): One of MONTHLY_DIRECT_DEBIT or MONTHLY_DIRECT_PAYMENT.
account_name (string, conditional, max 255 chars): The name associated with the bank account.
account_number (string, conditional): The bank account number.
account_sort_code (string, conditional): The bank account sort code.
payment_day (string, conditional): The preferred day of the month for the payment request. Must be in the range of 1-28.

billing_address (string, required)

An object with the following members.

address_line_1 (string, required, max 512 chars)

address_line_2 (string, conditional, max 512 chars)

address_line_3 (string, conditional, max 512 chars)

town (string, required, max 512 chars)

county (string, conditional, max 512 chars)

postcode (string, required, max 8 chars)

users (string, required)

An array of objects with the following members.

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

title (string, optional, max 255 chars)

given_name (string, required, max 255 chars)

family_name (string, required, max 255 chars)

date_of_birth (string, optional)

email (string, required, max 512 chars): Cannot be a email already in use for an existing account.

mobile (string, conditional, max 64 mobile)

landline (string, conditional, max 64 mobile)

opted_in_for_marketing (string, required)

psr (conditional)

An object with the following optional members describing Priority Services Register (PSR) details for the user.

requires_signup (boolean, conditional): A boolean to indicate that the user should be signed up to the PSR but the categories are unknown. Therefore the user requires contacting to determine which categories.

electricity_meter_points / gas_meter_points (required)

An array of objects with the attributes specified below.

Note:

At least one electricity or gas meter-point must be included.
A maximum of two electricity and one gas meter-point can be included.
All meter-points must be based in the Great Britain.
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 depending on the type of tariff specified.

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

tariff_code (string, required, max 255 chars)

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 (int, required): The estimated annual payment for this meter-point based on consumption. This value must be provided in pence.

consumption_standard (int, required if standard tariff)

The expected annual consumption for the standard register in kWh.

consumption_day (int, required if eco7 tariff)

The expected annual consumption for the day/peak register in kWh.

consumption_night (int, required if eco7 tariff)

The expected annual consumption for the night/off-peak register in kWh.

mpan / mprn (string, conditional, max 13 chars)

The meter-point identifier.

address (conditional)

An object with the following members.

address_line_1 (string, conditional, max 512 chars)

address_line_2 (string, optional, max 512 chars)

address_line_3 (string, optional, max 512 chars)

town (string, conditional, max 512 chars)

county (string, optional, max 512 chars)

postcode (string, conditional, max 8 chars)

meter_type (string, optional)

One of CREDIT or PREPAYMENT. The default is CREDIT.

has_smart_meter (boolean, optional)

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

current_supplier_name (string, optional, max 255 chars)

current_supplier_tariff (string, optional, max 255 chars)

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,
  },
  "electricity_meter_points": [
    {
      "unit_rate_uplift": "0.5"
    }
  ],
  "gas_meter_points": [
    {
      "unit_rate_uplift": "0.5"
    }
  ],
}

business (required)

An object with the following members.

name (string, required): The name of the business.
number (string, optional): The registered number of the business. This field is required for LIMITED businesses.
business_type (string, required): One of SOLE_TRADER, LIMITED, PARTNERSHIP, or CHARITY.
is_ccl_exempt (string, required): Whether the business is excempt from paying CCL (Climate Change Levy).
is_vat_exempt (string, required): Whether the business is excempt from paying VAT.
head_count (int, optional): The head count of the business, i.e. number of staff.
annual_turnover (int, optional): The estimated annual turnover in pounds £ (GBP).
unit_rate_uplift (float, optional): The amount to be added to the unit rate as commission (a string, pence per kWh). Must be between “0.0” and “2.0”.

Responses:

A successful submission will receive a 201 Created response with a payload of form:

{
  "number": "A-12341234"
}

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

GraphQL API¶

Octopus Energy also provides a GraphQL API for customers and partner organisations to interact with our platform. This is documented through the GraphQL Schema and in our Storybook.

API basics¶

Base URL¶

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

Note, all API requests must be made over HTTPS.

Authentication¶

Authentication is required for some queries and mutations. This is performed via setting the Authentication header for requests to be the appropriate token for a user. You can get a token for your user via the authentication mutations. For example, the EmailAuthentication mutation takes your username and password and returns a token. There is also a APIKeyAuthentication mutation using your developer API key.

Once you have your token, you can set the Authentication header using ModHeader, and use the GraphiQL interface provided to try out queries. Here is an example Viewer query to show you the details of the authenticated user.

To see examples of how these queries are used in practise, you can browse through our Storybook. There are a number of React components from the account management app with example queries which demonstrate how we fetch data to display to customers.

Table of Contents

Related Topics

Octopus Energy APIs¶

REST 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¶

Industry¶

List grid supply points¶

Quotes¶

Create a quote¶

Accounts¶

Create an account¶

GraphQL API¶

API basics¶

Base URL¶

Authentication¶