Skip to main content

​
Energy Contract Parameters

Energy contracts define pricing information for user electricity consumption, supporting yearly, monthly, and spot hourly pricing models.
Energy contracts can be linked to a specific building or set at the user level for all buildings.

​
Required Parameters

​
owner
string (UUID)
required
User ID that owns this energy contract.Example: 016b78a7-0c7c-4241-a277-015c3ad3cb90Writable: No (set at creation)

​
Contract Information

​
building
string (UUID)
Building ID this contract applies to. Optional - if not provided, contract applies to all user buildings.Example: 016b78a7-0c7c-4241-a277-015c3ad3cb90Writable: Yes
​
meter_id
string
ID of the electricity meter for this contract.Example: 125328591095Writable: Yes
​
supplier
string
Name of the energy supplier.Example: Good Energy CompanyWritable: Yes
​
energy_contract_type
enum
Type of energy contract pricing model.Options: Yearly, Monthly, Spot HourlyExample: Spot HourlyWritable: Yes

​
Pricing Information

​
energy_price
array
Energy price in currency/kWh. Array of JSON objects with price (float) and timestamp (ISO format string).For constant pricing, provide a single entry. For variable pricing, provide multiple entries with timestamps.Example:
[
  {
    "price": 0.20,
    "timestamp": "2023-11-01T00:00:00+00:00"
  }
]
Writable: Yes
​
currency_energy_price
string
Currency of the energy price in ISO 4217 format. Required when providing hourly energy prices.Example: EURWritable: Yes
​
energy_price_includes_external_components
boolean
Flag indicating whether the provided energy price includes external components such as grid fees and taxes.If false, wholesale spot price is assumed.Example: trueWritable: Yes

​
Usage Examples

​
Create Contract with Yearly Fixed Price

curl -X POST \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/energy-contracts' \
  -H 'Authorization: Bearer {auth_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "energy_contract_type": "Yearly",
    "supplier": "Good Energy Company",
    "meter_id": "125328591095",
    "energy_price": [
      {
        "price": 0.25,
        "timestamp": "2024-01-01T00:00:00+00:00"
      }
    ],
    "currency_energy_price": "EUR",
    "energy_price_includes_external_components": true
  }'

​
Create Contract with Spot Hourly Pricing

curl -X POST \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/energy-contracts' \
  -H 'Authorization: Bearer {auth_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "building": "016b78a7-0c7c-4241-a277-015c3ad3cb90",
    "energy_contract_type": "Spot Hourly",
    "supplier": "Dynamic Energy Co",
    "energy_price": [
      {"price": 0.15, "timestamp": "2024-01-15T00:00:00+00:00"},
      {"price": 0.18, "timestamp": "2024-01-15T01:00:00+00:00"},
      {"price": 0.22, "timestamp": "2024-01-15T02:00:00+00:00"}
    ],
    "currency_energy_price": "EUR",
    "energy_price_includes_external_components": false
  }'

​
Update Energy Prices

curl -X PUT \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/energy-contracts/{contract_id}' \
  -H 'Authorization: Bearer {auth_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "energy_price": [
      {"price": 0.19, "timestamp": "2024-02-01T00:00:00+00:00"}
    ]
  }'

​
Contract Types Explained

A single fixed price that applies for the entire year. Provide one price entry with the start date of the contract period.Best for: Customers with fixed-rate annual contracts.
A fixed price that may change monthly. Provide one price entry per month with the effective date.Best for: Customers with contracts that adjust monthly based on market conditions.
Variable pricing that changes hourly based on wholesale spot prices. Provide 24 price entries per day.Best for: Customers with dynamic pricing contracts who want to optimize consumption based on real-time prices.
Spot hourly pricing enables the most effective optimization by shifting energy-intensive operations to low-cost hours.

​
Best Practices

  • Update spot hourly prices daily or as frequently as your data source provides
  • For yearly/monthly contracts, update when price changes are known
  • Always provide timestamps in ISO 8601 format with timezone
  • Include all 24 hours when updating spot hourly prices
  • Set energy_price_includes_external_components to true if your price includes grid fees, taxes, and levies
  • Set to false if providing only wholesale spot prices
  • This affects optimization calculations for self-consumption scenarios
  • Leave building empty for user-level pricing (applies to all buildings)
  • Set specific building ID when a user has multiple properties with different energy contracts
  • Building-specific contracts override user-level pricing
  • Always provide currency_energy_price in ISO 4217 format (e.g., EUR, USD, GBP)
  • Ensure all prices for a contract use the same currency
  • Currency must match your organization’s configured billing currency

User Management

Managing end-users and contracts

Setting Preferences

How users configure energy settings

Users

User parameters reference

Buildings

Building parameters reference