Using API to create and manage tariffs
In this tutorial, you will learn how to import and manage your customer’s tariffs in FlatPeak when you cannot use Connect.
Introduction
Depending on their energy market structure and choices, your customer may be on multiple tariffs simultaneously. For instance, they might buy electricity from Company A while paying Company B for transmitting that electricity to their home.
Understanding tariffs in FlatPeak
FlatPeak stores tariff information about the supply address and the direction of energy transfer to which this tariff applies. Because multiple tariffs may apply to a location simultaneously, forming the location “tariff,” FlatPeak refers to them as “tariff elements.”
Tariff direction and type
To enable any business case, FlatPeak supports four combinations of tariff type and energy transfer direction:
| Type/Direction | Description |
|---|---|
COMMODITY+IMPORT | The price of the actual imported electricity. It’s essential always to allow your customers to add their commodity import tariff, as this is the most fundamental fee across all markets and regions. |
NON_COMMODITY+IMPORT | The cost of transporting electricity, known as network or grid fees, may be charged separately in many markets. FlatPeak recommends allowing customers to add this tariff, as it affects their total energy cost. |
COMMODITY+EXPORT | The price of exported electricity. If your solution includes energy storage or generation, you should offer this option. FlatPeak separates import and export tariffs, as customers may use different providers. |
NON_COMMODITY+EXPORT | The price of transporting electricity from the customer to the grid. FlatPeak disabled this feature as there are no known cases of export transmission fees. |
COMMODITY type represents contract to purchase “electrons”. NON_COMMODITY type represents the contract to pay for the transfer of those electrons from the power station to the customer’s home.What you can do using tariffs API endpoints
The tariffs element API endpoints enable you to perform all basic actions regarding tariffs in FlatPeak, except for working with tariffs created using a DIRECT connection to their energy provider systems using Connect. These tariffs can only be viewed or deleted.
Object relationships
FlatPeak stores tariffs about the supply address, referred to as Location. While Location is required to create Tariff objects, you may also choose to import your Customer objects structure for consistency:
- Customer object relates to Location objects as one-to-many.
- In turn, the Location object relates to Tariff objects as one-to-many.
Importing your customer tariffs from your systems to FlatPeak
Follow the steps below when you want to import your customer’s tariffs to FlatPeak:
Create Customer object
To create a Customer object, call the customer-create endpoint, passing your internal customer reference as reference_id. In the example below, the response will include FlatPeak Customer ID, cus_65e421d1daa4a24082b4f590.
Create Location object
You must create a Location object before you start creating tariffs for it. To create a Location object, call location-create endpoint passing your internal location reference as reference_id. The response will include FlatPeak Location ID, loc_641b90b758fb8e6293716e40 in the example below.
To create a location, you must pass at least postal_address.city and postal_address.country_code. This is so FlatPeak can resolve timezone, currency code and market rates region from the address provided.
Create Tariff object
Now that you have a Location ID, you can create a tariff object.
The FlatPeak tariff object is complex as it provides for very advanced tariffs that may include market rate elements, transmission fees, consumption-based tiers, seasonal and special day variations, and more.
In the example below, we will create a simple tariff where a customer pays approximately €0.23 per KWh:
| Object/Parameter | Description |
|---|---|
location_id | FlatPeak Location ID, this tariff applies to. |
direction | Tariff direction, i.e. if it applies to the energy being consumed IMPORT at the supply address or exported from that address, i.e. EXPORT. The most common value will be IMPORT. |
type | Represents if the tariff describes energy purchase (COMMODITY) or transmission (NON_COMMODITY) cost, see tariff direction and type. The most common value will be COMMODITY. |
contract_start_date | Date when the contract between your customer and their energy provider has begun. If you don’t have this information, set it to today’s date. |
contract_end_date | Date when the contract between your customer and their energy provider has ended or will end. If you don’t have this information, set it to today’s date + 1 year. |
schedule.months | Specifies months when tariff applies. Set to All. |
schedule.days_and_hours.days | Specifies days when tariff applies. Set to All. |
schedule.days_and_hours.hours.[] | Specifies hours when this tariff applies. Set to align with the example below when your customer is on a fixed tariff rate. Set rates.value to their tariff rate in small currency units, i.e. 23.431 for ~€0.23. |
You have now successfully imported your customer’s tariff to FlatPeak. Refer to Calculating Energy Cost, Calculating Cost Savings and other guides to learn how to make use of Tariff data to optimise your customer’s energy cost, report savings and more.
Working with tariffs
Was this page helpful?