Pricing plans are the primary request of the pricing API, they provide access to a given network reporting regions prices. Covering all supported electricity providers, every usage type and plan variation available.

Prerequisites

Before you can follow this guide, you will need:

To be able to make a request in your programming language of choice, our API reference has example requests using multiple common languages and libraries, just look for the "Language" dropdown at the top of the page.
Your subscription key (32 alphanumerical combination key).

Making the Request

Using your language of choice, make a GET request to the https://api.ahiko.io/v1/plans endpoint, with the following headers:

ahiko-app-id {{application subscription key}}

Where the {{application subscription key}} is replaced with your application subscription key.

Handling Errors

The Ahiko API returns standard HTTP response codes.
Below are the most common error codes and their reasons:

200 Everything is OK. The response is included in the body.
404 The url does not exist. Check you have entered the url correctly.
403 You are not allowed to access this resource. Make sure you have a valid user access token with the correct permissions. Also make sure you have set the Authorization header correctly (note the American spelling).

You should treat any response code that is greater than 399 as an error.

Handling the Response

The Ahiko API uses JSON to encode responses. Most languages have libraries to encode and decode JSON.

The API response will look like:

{
  "success": true,
  "data": [
    {
      "version": "3",
      "created_at": "2023-09-06T18:01:07.908190Z",
      "updated_at": "2023-09-16T18:02:27.093721Z",
      "id": "b2d50b04-b521-410b-8a2d-5738be4c9a47",
      "lifecycle": "active",
      "network_reporting_region": "1",
      "provider": {
        "name": "Electric Kiwi",
        "id": "provider_tmkykkpdcn2kglsy4ylxmzv7kf"
      },
      "pricing_plans": [
        {
          "user_pricing": "standard",
          "plan": "Kiwi",
          "gst_type": "exclude",
          "settings": {
            "daily_1_hour_free": false
          },
          "prices": {
            "daily": {
              "unit": "$/day",
              "price": 2.29
            },
            "solar_export": {
              "unit": "$/kwh",
              "price": -0.11
            },
            "price_periods": [
              {
                "name": "peak",
                "unit": "$/kwh",
                "price": 0.3771,
                "label":"anytime",
                "time_periods": [
                  {
                    "start_time": null,
                    "end_time": null
                  }
                ]
              }
            ],
            "weekend_price_periods": []
          }
        }
      ]
    }
  ]
}

Lets break this response down a bit:

At the top level, the key success is true. That means that the request was successful.

The data key contains a list of Ahiko Pricing Plans, with various information.

Pricing Plan Meta Data

The pricing plan meta data is data that is available at the top level of the data payload received in the plans response. It contains general information around the origin, timing and location of the data.

{
  ...
  ... [
    {
      "version": "3",
      "created_at": "2023-09-06T18:01:07.908190Z",
      "updated_at": "2023-09-16T18:02:27.093721Z",
      "id": "b2d50b04-b521-410b-8a2d-5738be4c9a47",
      "lifecycle": "active",
      "network_reporting_region": "1",
      "provider": {
        "name": "Electric Kiwi",
        "id": "provider_tmkykkpdcn2kglsy4ylxmzv7kf"
      },
      "pricing_plans": [...]
    }
  ]
}

`version : string (integer)`

The version of the message protocol. Whilst the url of the API request contains a version, we also include the message version in the body.

`created_at : string (datetime)`

The first time we observe that a pricing plan in its current form is made available by an energy provider. We capture this moment in time in accordance with the ISO 8601 protocol, where all times are capturing in UTC format. If any aspect of the pricing plan changes (price, timings etc.) a brand new pricing plans is created, reflected with a new created_at time.

`updated_at : string (datetime)`

Every time we observe that the pricing plan remains unchanged (daily) we reflect this by updating the updated_at. This allows you to observe how long a plan has been in effect (difference between created_at and updated_at). We capture this moment in time in accordance with the ISO 8601 protocol, where all times are capturing in UTC format.

`id :string`

Unique identifier for a given price plan, guaranteed to be uniquely created when a new plan is created, reflected by created_at.

`lifecycle :string`

A plan can be in 1 of 2 states, either active or archived. A plan upon creation is in an active state and will remain in that state if nothing about the contents changes. If a plan is deems to still be active it will be reflected by a frequent updating of the updated_at. Eventually when a plan changes or is no longer applicable it will be reflected by the state transitioning to archived.

`network_reporting_region : string (integer)`

The number referencing the network reporting region for the current pricing plan. See here for more information on network reporting regions and the associated API.

`provider`

The provide represents a JSON object consisting of 2 parts:

name : string The name of the energy provider.
id : string The unique identifier for the energy provider, guaranteed to be constant throughout the lifetime of the provider.

Pricing Plans (`pricing_plans: list`)

At it's most basic, an Ahiko pricing plan is something that has a price. Some plans have lots of prices (for different scenarios such as time of data and period, while others may only have one. Different types of plans have different arrangement but fundamentally the building blocks are all the same.

{
  ... 
  [{
      ...,
      "pricing_plans": [
        {
          "user_pricing": "standard",
          "plan": "Kiwi",
          "gst_type": "exclude",
          "settings": {
            "daily_1_hour_free": false
          },
          "prices": {...}
        }
      ]
    }
  ]
}

The pricing plan details are captured in an array JSON object within the pricing_plans key. The following are important keys in the data:

`user_pricing : string (enum: [low | standard])`

A simple enumeration of low or standard pricing which a user gets to chose for their household per ICP.

`plan : string`

A free form name provided by the Electricity Retailer that is used to describe their energy plan

`gst_type : string (enum: [include | exclude])`

A simple enumeration of include or exclude to reflect whether GST has been included or excluded from the price(s) provided by the retailer. Typically the prices are excluded from GST, but this keeps it explicit.

`settings : JSON object`

Setup to be able to extend where needed, but initially only supports:

daily_1_hour_free Which is used to represent where 1 hour of the data is assumed to be free in the pricing.

Prices (`prices: list`)

Within a pricing plan, beyond's is core configuration lies the actual prices, everything from the daily price all the way down to very specific timings of different prices. The model is such that it supports price variation in small intervals and an ability to differentiate prices during weekdays from those at the weekend.

{
  ...
  [{
      ...,
      "pricing_plans": [
        {
          ...
          "prices": {
            "daily": {
              "unit": "$/day",
              "price": 2.29
            },
            "solar_export": {
              "unit": "$/kwh",
              "price": -0.11
            },
            "price_periods": [
              {
                "name": "peak",
                "unit": "$/kwh",
                "price": 0.3771,
                "time_periods": [
                  {
                    "start_time": "09:00",
                    "end_time": "17:00"
                  },
								  {
                    "start_time": "21:00",
                    "end_time": "23:00"
                  },
                ]
              },
							{
                "name": "offpeak",
                "unit": "$/kwh",
                "price": 0.1240,
                "time_periods": [
                  {
                    "start_time": "17:00",
                    "end_time": "21:00"
                  },
								  {
                    "start_time": "23:00",
                    "end_time": "09:00"
                  },
                ]
              },
            ],
            "weekend_price_periods": []
          }
        }
      ]
  }]
}

The prices are captured in an array JSON object within the prices key. The following are important keys in the data:

`daily : JSON object`

An important field in all of the pricing plan, the daily object consists of a unit typically $/day and a price represented as a float. This amount is the daily amount that the Energy provider will charge the customer regardless of their daily consumption. This is a flat rate.

`solar_export : JSON object`

Provides the export flat price for the said provider. The solar_export object consists of a unit typically $/kwh and a price represented as a float. The amount will be negative to reflect the direction of money as a money received by the exporting household.

Price Periods (`price_periods : list`)

The core of the pricing_plan is the pricing_periods. This is where the granular, flexible pricing is captured, unique to each plan. If the list is empty (denoted by []), then it means that only the daily price is to be applied for the named plan. Otherwise, there are multiple key attributes:

`name : string (enum: [peak | offpeak | night])`

A simple enumeration of one of 3 names used to describe a period. Whilst there can be up to 3 it is perfectly acceptable for there to be done as denoted by the "price_periods": [].

`unit : string`

Typically "$/kwh", this is the unit for the associated price.

`price : float`

Associated price for the period.

`label : string (enum: [anytime | day | night | peak | offpeak | night]`

An optional label that describes the value of the price

`time_periods : list`

A time_periods will always be present if the price_period detail is provided. There can be 1 or many time_periods represented, each object within the list consists of 2 parts:

start_time : string - the start time as a string in the format HH:mm defined by Microsoft date and time standards.
end_time : string - the end time as a string in the format HH:mm

Note that to define a start_time and end_time period for the entire interval is denoted by setting both to null.

Weekend Price Periods (`weekend_price_periods : list`)

Identical in structure to the price_periods, however, it is applicable only to the prices on both Saturday and Sunday. When it is not present (denoted by [] empty array), it means that the price_periods are applied to every day of the week (including weekends). Think of it like an override for weekend

Prerequisites

Making the Request

Handling Errors

Handling the Response

Pricing Plan Meta Data

version : string (integer)

created_at : string (datetime)

updated_at : string (datetime)

id :string

lifecycle :string

network_reporting_region : string (integer)

provider

Pricing Plans (pricing_plans: list)

user_pricing : string (enum: [low | standard])

plan : string

gst_type : string (enum: [include | exclude])

settings : JSON object

Prices (prices: list)

daily : JSON object

solar_export : JSON object

Price Periods (price_periods : list)

name : string (enum: [peak | offpeak | night])

unit : string

price : float

label : string (enum: [anytime | day | night | peak | offpeak | night]

time_periods : list

Weekend Price Periods (weekend_price_periods : list)