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_codeThe 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
termis the number of months that a product lasts for if it is fixed length.Each
*_tariffsobject 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_atdatetime 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_codeThe code of the product to be retrieved, for example
VAR-17-01-11.tariff_codeThe 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:
mpanThe 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 / mprnThe electricity meter-point’s MPAN or gas meter-point’s MPRN.
serial_numberThe 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
arrayofobjectwith 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
gsporpostcodemust be included. All meter-points must be based in the UK, excluding Northern Ireland. All meter-points must belong to the samegsporpostcode.For an electricity meter-point, at least one of
consumption_standardor a combination ofconsumption_dayandconsumption_nightmust be included. For three register meters,consumption_day,consumption_nightandconsumption_off_peakmust be included.For a gas meter-point,
consumption_standardmust be included.gspThe grid supply point.
postcodeThe postcode of the property. You only need to provide this if you are unable to provide a
gsp.consumption_standardThe standard consumption of a single register electricity or gas meter-point.
consumption_dayThe day consumption of a dual or three register electricity meter-point.
consumption_nightThe night consumption of a dual or three register electricity meter-point.
consumption_off_peakThe off-peak consumption of a three register electricity meter-point.
has_smart_meterWhether a smart meter is installed. The default is
false.mpanThe 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
arrayof Octopus Energy product codes to create quotes for.business_products_onlyWhether to create business quotes instead of domestic. The default is
false. When set totrueonly 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",
"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,
"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 Requestresponse.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
DOMESTICorBUSINESS.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_FACEorINTERNET.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.
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,HALF_HOURLYorDENIED. This is the read permission frequency the occupier grants to meter readings from smart meters.smart_meter_interest(string, optional)One of
SMETS2_INTEREST_INTERESTED,SMETS2_INTEREST_NOT_AT_THE_MOMENTorSMETS2_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_DEBITbut are optional if all the meters are of typePREPAYMENT. TheMONTHLY_DIRECT_PAYMENTmethod is not available to all users.method(string, required)One of
MONTHLY_DIRECT_DEBITorMONTHLY_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
mobileorlandlinemust 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
booleanto 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
mpanoraddressmust be included. At least one ofconsumption_standard(standard tariff) or a combination ofconsumption_dayandconsumption_night(two-rate tariff) orconsumption_day,consumption_nightandconsumption_off_peak(three-rate tariff) must be included depending on the type of tariff specified.For a gas meter-point, at least one of
mprnoraddressmust be included, as well asconsumption_standard.tariff_code(string, required, max 255 chars)The tariff code as stored by the supplier. Must match an available tariff on the
sold_atdatetime 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 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
CREDITorPREPAYMENT. 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 valuePREPAYMENTshould 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
LIMITEDbusinesses.business_type(string, required)One of
SOLE_TRADER,LIMITED,PARTNERSHIP, orCHARITY.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”.
bespoke_tariff_rates(dict, optional)A json object containing bespoke tariff rates, if applicable.
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:
STANDARDorECO7_DAYorECO7_NIGHTorOFF_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.
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
STANDARDorECO7_DAYorECO7_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.
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 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 Authorization header for requests to be the appropriate token for a user. You can get a token for your user via the authentication mutations. There are several mutations available for authentication, but we recommend the ObtainKrakenToken mutation, which can be used in several different ways, including email/password, an API key or a pre-signed key. Some mutations have been deprecated, and their use is not recommended; they are marked as deprecated in the documentation, which can be viewed at the base url.
Once you have your token, you can set the Authorization 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.
Organisation level authentication can be achieved using the following steps: 1. 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) 2. View the secret key 3. Copy/paste the secret key into the ModHeader Authorization header 4. Now you can access the query/mutations in GraphiQL that this organisation has permission to use
If you would like to authenticate using a Kraken JWT, you can do so by adding the Authorization header with
JWT your-token as the value. Notice your token needs to be prepended with JWT or Kraken will interpret
this token as an external (AWS Cognito) token.
To see examples of how these queries are used in practice, 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.