Table of Contents
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.
Sharing a quote via email.
Creating an 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,
"exit_fees_type": "NONE",
"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"
},
]
}
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)Aggregates consumption over a specified time period. A day is considered to start and end at midnight in the server’s timezone. The default is that consumption is returned in half-hour periods. Accepted values 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-19T00:30:00+0100",
"interval_end": "2018-05-19T01:00:00+0100"
},
{
"consumption": 0.071,
"interval_start": "2018-05-19T00:00:00+0100",
"interval_end": "2018-05-19T00:30:00+0100"
},
{
"consumption": 0.073,
"interval_start": "2018-05-18T23:30:00+0100",
"interval_end": "2018-05-18T00:00:00+0100"
}
]
}
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
ofobject
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
orpostcode
must be included. All meter-points must be based in the UK, excluding Northern Ireland. All meter-points must belong to the samegsp
orpostcode
.For an electricity meter-point, at least one of
consumption_standard
or a combination ofconsumption_day
andconsumption_night
must be included. For three register meters,consumption_day
,consumption_night
andconsumption_off_peak
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 or three register electricity meter-point.
consumption_night
The night consumption of a dual or three register electricity meter-point.
consumption_off_peak
The off-peak consumption of a three 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.
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.
product_codes
(required)An
array
of product codes to create quotes for.business_products_only
Whether to create business quotes instead of domestic. The default is
false
. When set totrue
only a single electricity meter-point must be included with an associatedmpan
.
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_off_peak": 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_off_peak": 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,
"referral_code": "some-referral-123",
"quote_code": "1981fd3936cc4cfda70b2e697347b885",
"affiliate": {},
"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,
"opted_in_to_third_parties": 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
}
}
],
"metadata": [
{
"key": "metadata_key",
"value": {
"melo": 10284,
"some_data": "some_value"
}
}
]
}
Parameters:
reference
(string, max 64 chars, required)A unique partner reference. The reference provided should be unique per switch. Requests where a duplicate reference has been provided and the existing enrolment has not previously been rejected will receive a
400 Bad Request
response.account_reference
(string, max 128 chars, optional)A unique reference to previous external account number or similar account identifier. The account reference must be in NAMESPACE-VALUE format.
sold_at
(string, required)A datetime of when the account sale was made.
account_type
(string, required)One of
DOMESTIC
orBUSINESS
.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
orINTERNET
.sales_channel
(string, optional)One of
DIRECT
,PRICE_COMPARISON
,TELESALES
,DIGI_TELESALES
,EVENTS
,FIELD_SALES
,AGGREGATOR
,PARTNERSHIPS
,NEW_TENANT
,MOVE_IN
,WORKPLACE_POP_UP
,BROKER
.sales_subchannel
(string, optional)An optional segmentation of the sales channel, e.g. the names of the specific price comparison site, or the telesales organisation.
affiliate
(object, optional)An object with the following fields.
signup_reward_code
(str, optional)The code of an existing signup reward referral scheme that will be used for giving credit to the created account as a signup reward.
organization_name
(str, optional)The name of an existing organization that will be used to create an account for an affiliate.
quote_code
(str, optional)The code of an existing legacy quote created using the legacy
CreatQuote
mutation as part of the join supplier journey for this new customer. If the quote was generated as part of an affiliate session, the affiliate link and any query parameters belonging to the session will be associated with the created account.Note: only one of
quote_code
andquote_request_code
should be provided in the input.quote_request_code
(str, optional)The code of an existing quote which was created using the
QuoteNewMeterPoints
mutation as part of the join supplier journey for this new customer. If the quote was generated as part of an affiliate session, the affiliate link and any query parameters belonging to the session will be associated with the created account.Note: only one of
quote_code
andquote_request_code
should be provided in the input.is_change_of_tenancy
(string, required)Whether this account is a change of tenancy at the property.
referral_code
(string, optional)The referral code of an existing account linked to a Kraken referral scheme.
smart_meter_read_permission
(string, optional)One of
MONTHLY
,DAILY
orHALF_HOURLY
. This is the read permission frequency the occupier grants to meter readings from smart meters.requires_postal_comms
(boolean, optional)Communication delivery preference, when requires_postal_comms is True, then set to POSTAL, else set to EMAIL, when not provided it will be null.
smart_meter_interest
(string, optional)One of
SMETS2_INTEREST_INTERESTED
,SMETS2_INTEREST_NOT_AT_THE_MOMENT
orSMETS2_INTEREST_NOT_INTERESTED
. The occupier’s interest in installing a smart meter.smart_onboarding_product_type
(string, optional)A code to indicate which type of smart tariff the customer is meant to onboard onto. This is a restricted option. Please get in touch for information on whether this can be enabled and what the allowed options are.
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, optional)An object with the following members. The payment details are required when using the method
MONTHLY_DIRECT_DEBIT
but are optional if all the meters are of typePREPAYMENT
. TheMONTHLY_DIRECT_PAYMENT
method is not available to all users.method
(string, required)One of
MONTHLY_DIRECT_DEBIT
orMONTHLY_DIRECT_PAYMENT
orBILL_TRIGGERED_DIRECT_DEBIT
.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. Only required for
MONTHLY_DIRECT_DEBIT
schedules.
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
orlandline
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)opted_in_to_third_parties
(bool, optional)credit_score_data
(Optional)An optional object but if present in the users structure it has to have the following required fields.
score
(int, required)risk_bracket
(string, required)One of
LOW
,MID
,HIGH
, orUNKNOWN
.
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
oraddress
must be included. At least one ofconsumption_standard
(standard tariff) or a combination ofconsumption_day
andconsumption_night
(two-rate tariff) orconsumption_day
,consumption_night
andconsumption_off_peak
(three-rate tariff) must be included depending on the type of tariff specified.For a gas meter-point, at least one of
mprn
oraddress
must be included, as well asconsumption_standard
.tariff_code
(string, max 255 chars, required if no ``quote_request_code``)The tariff code as stored by the supplier. Must match an available tariff on the
sold_at
datetime for the authenticating partner. Required if noquote_request_code
is supplied.quoted_product_id
(int, required if ``quote_request_code`` is supplied)The ID of the market supply quoted product returned by the
QuoteNewMeterPoints
orQuoteNewMeterPointsOnBespokeProducts
mutation which was selected by the customer for this meter point. Required if aquote_request_code
is supplied.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. For business quotes, the price is exclusive of VAT, while for non-business quotes, it should be inclusive of VAT.
consumption_standard
(int, required if standard tariff)The expected annual consumption for the standard register in kWh.
consumption_day
(int, required if eco7 or three-rate tariff)The expected annual consumption for the day/peak register in kWh.
consumption_night
(int, required if eco7 or three-rate tariff)The expected annual consumption for the night/off-peak register in kWh.
consumption_off_peak
(int, required if three-rate tariff)The expected annual consumption for the additional 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
orPREPAYMENT
. The default isCREDIT
, which represents any kind of traditional credit meter or smart meter. This field is mandatory for traditional prepay meters, for which the valuePREPAYMENT
should be used.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)metadata
(list, optional)An array of key value pairs for storing generic metadata relating to an account.
key
(string, required)Key on which the metadata will be stored on
value
(dict, required)A json object containing any arbitrary piece of data to store in relation to the account.
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",
"bespoke_tariff_rates": {
"standing_charge": "13.25",
"unit_rates": [
{
"unit_rate": "12.6",
"rate_type": "STANDARD"
}
]
}
}
],
"gas_meter_points": [
{
"unit_rate_uplift": "0.5"
"bespoke_tariff_rates": {
"standing_charge": "13.25",
"unit_rate": "3.25"
}
}
],
}
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
,CHARITY
, orGOVERNMENT
.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).
bespoke_tariff_rates
(dict, optional)A json object containing bespoke tariff rates, if applicable. Cannot be used in conjunction with
bespoke_pps_tariff_rates
.standing_charge
(decimal, required)The value in pence per day of the charge (excluding VAT).
unit_rate
(decimal, optional)The value in pence per kWh of the charge (excluding VAT). This field should be used for gas meters.
unit_rates
(array, optional)For elec meters, the unit rates are provided on a per register basis in this array.
rate_type
(string, required)The rate type of the unit rate. One of:
STANDARD
orECO7_DAY
orECO7_NIGHT
orOFF_PEAK
.unit_rate
(decimal, required)The value in pence of the charge (excluding VAT).
bespoke_pps_tariff_rates
(array, optional)An array of json objects containing bespoke PPS tariff rates, if applicable. If supplied, the array must contain exactly 2 objects, one for direct debit bespoke rates and another for non-direct debit bespoke rates. Cannot be used in conjunction with
bespoke_tariff_rates
.standing_charge
(decimal, required)The value in pence per day of the charge (excluding VAT).
unit_rate
(decimal, optional)The value in pence per kWh of the charge (excluding VAT). This field should be used for gas meters.
payment_method
(string, optional)The payment method for the rate. One of:
DD
(Direct debit) orNDD
(Non-direct debit).unit_rates
(array, optional)For elec meters, the unit rates are provided on a per register basis in this array.
rate_type
(string, required)The rate type of the unit rate. One of:
STANDARD
orECO7_DAY
orECO7_NIGHT
orOFF_PEAK
.unit_rate
(decimal, required)The value in pence of the charge (excluding VAT).
Responses:
A successful submission will receive a 201 Created
response with a payload of form:
{
"number": "A-12341234"
}
A submission which has incurred an error, but requires further investigation from a member of our
team in order to complete the request, will receive a 202 Accepted
response with a payload:
{
"detail": "We are unable to create an account, however the error will be investigated
internally."
}
Submissions that incur validation errors that cannot be fixed by a member of our team will receive
a 400 Bad Request
response detailing the errors.
Note that all serializers in this file that raise a ValidationError should first save an AccountEnrolmentEvent. To do this simply call one of:
_raise_enrolment_validation_error_not_for_manual_investigation(…)
_raise_enrolment_validation_error(…)
As opposed to passing validators directly into serializer fields, we should write a custom validate method which returns _validate_field(…), e.g:
def validate_<your_field>(self, value):
return _validate_field(normalizer=<your_validator>, value=value, ...)
Business tariff renewal¶
Warning
This endpoint is only available to partner organisations.
This end-point allows a new agreement to be created for an existing account. It is restricted to business accounts.
Request:
POST /v1/accounts/{account_number}/tariff-renewal/
Sample payload:
{
"agreements": [
{
"mpxn": "1013004420117",
"tariff_code": "E-1R-SOME-PRODUCT-J",
"valid_from_date": "2019-12-01",
"valid_to_date": "2020-12-01",
"bespoke_tariff_rates": [
{
"meter_serial_number": "Z16N389556",
"standing_charge": 3.25,
"registers": [
{
"register_identifier": "1",
"unit_rate": 15.6
}
],
}
],
"commission": {
"affiliate_organisation_name": "Some Partner",
"unit_rate_uplift": "1.00",
},
},
{
"mpxn": "9113681703",
"tariff_code": "G-1R-SOME-PRODUCT-J",
"valid_from_date": "2019-12-01",
"valid_to_date": "2020-12-01",
"bespoke_tariff_rates": [
{
"meter_serial_number": "GA1244364577",
"standing_charge": 3.25,
"unit_rate": 15.6
}
],
"commission": {
"affiliate_organisation_name": "Some Partner",
"unit_rate_uplift": "1.00",
},
},
]
}
Parameters:
agreements
(array, required)List of all agreements to be created to the given account.
mpxn
(string, required)MPRN or MPAN of the meter point getting a new agreement.
tariff_code
(string, required)Tariff code for the new agreements.
valid_from_date
(date, required)Date (inclusive) the new agreement is valid from. The format should be “%Y-%m-%d”.
valid_to_date
(date, optional)Date (exclusive) the new agreement is valid to. The format should be “%Y-%m-%d”.
bespoke_tariff_rates
(array, optional)Bespoke tariff rates for the new agreement, if applicable.
meter_serial_number
(string, required)Meter serial number to which the bespoke tariff applies
standing_charge
(decimal, required)The value in pence per day of the charge (excluding VAT).
unit_rate
(decmical, optional)The value in pence per kWh of the charge (excluding VAT). This field should be used for gas meters.
registers
(array, optional)For elec meters, the unit rates are provided on a per register basis in this array
register_identifier
(string, optional)The identifier of the register to which this unit rate applies.
rate_type
(string, optional)The rate type of the unit rate. One of
STANDARD
orECO7_DAY
orECO7_NIGHT
. If the register_identifier is not provided, the rate type must be provided instead.unit_rate
(decimal, required)The value in pence of the charge (excluding VAT).
commission
(dict, optional)Commission applicable to this tariff renewal.
affiliate_organisation_name
(string, required)Name of the affiliate organisation due the commission for this agreement.
affiliate_link_subdomain
(string, optional)Sub-domain of the affiliate link due the commission for this agreement.
unit_rate_uplift
(decimal, required)Uplift in pence to be paid to the affiliate.
Responses:
A successful submission will receive a 201 Created
response with the original payload and
an additional field for the account number, e.g. the below for a simple original payload.
{
"account_number": "A-12AB34CD",
"agreements": [
{
"mpxn": "1013004420117",
"tariff_code": "E-1R-SOME-PRODUCT-J",
"valid_from_date": "2019-12-01",
"valid_to_date": "2020-12-01"
}
]
}
Any validation or domain errors will receive a 400 Bad Request
response detailing the errors,
such as
{
"errors": [
"Account is not a business account."
]
}
If the account does not exist, a 404 Not Found
response is returned.
If incorrect authentication is used, a 401 Unautharized
response is returned.
If the caller has insufficient permissions for this action, a 403 Forbidden
response is
returned.
In case of an intermittent error, a 500 Internal Server Error
response is returned. If the
error persists, please get in touch with the support team.
Possible validation errors are: * Affiliate organisation {name} does not exist. * Electricity meter point with MPAN {mpxn} does not exist. * Gas meter point with MPRN {mpxn} does not exist. * Unknown meter point type for {mpxn}. * No {fuel_type} tariff found for the tariff code {tariff_code}. * Agreement valid_to_date {valid_to_date} cannot be earlier than agreement valid_from_date {valid_from_date} * A register with identifier {register_identifier} does not exist on meter {meter_serial_number} on meter point {mpxn}. * A meter with serial number {meter_serial_number} does not exist on meter point {mpxn}. * If commission data is provided the agreement needs to have an end date. * One of register_identifier and rate_type must be provided for bespoke electricity rates. * Duplicate bespoke rates received for {mpxn}. * Bespoke tariff rates are not currently supported.
Possible domain errors are: * Account with number {account_number} does not exist * Account is not a business account * Current agreement on meter point is not for the same account * Current agreement already has a follow on agreement * Current agreement does not end at new agreement start date * More than one contract in place for meter point * Current meter point contract terminates after new agreement start date * More than one future agreement in place
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.
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 Authorization header for requests to be the appropriate token for a user. You can get a token for your user via the obtainKrakenToken mutation, which can be used in several different ways, including email/password, an API key or a pre-signed key.
Here is an example of how to get a Kraken token using the GraphiQL interface.
Once you have your Kraken token, you can set the Authorization header on your requests to be that token and try out some queries. If you are using the GraphiQL interface, you can set the header via the provided header tab.
Here is an example Viewer query to show you the details of the authenticated user.
Organisation level authentication can be achieved using the following steps:
Browse to https://kraken.octopus.energy/affiliates/organisations/ and select the organisation you wish to impersonate (you may need to request permission to view this page)
View the secret key
Copy/paste the secret key into the Authorization header:
{"Authorization":"sk_live_12345"}
Now you can access the query/mutations in GraphiQL that this organisation has permission to use