Products and Tariffs: Pricing in Lumenaza Contracts

In Lumenaza, a product is the pricing plan attached to a contract. It defines what a consumer pays (or a producer receives) for energy, how long the pricing is valid, and the minimum commitment and notice period that governs the contract relationship. Products are selected by name when a contract is created and can be switched to a different plan while a contract is active.

Product structure

Every product contains at least two price components:

Component	Description
Base fee	A fixed recurring charge (e.g. monthly standing charge), independent of consumption.
Working price	A per-kWh charge applied to actual energy consumed or fed in.

Additional fields on a product:

Field	Description
`product_name`	The unique string identifier used to select a product when creating or switching a contract.
`valid_from`	The date from which this product pricing is effective.
`valid_until`	The date after which this product pricing is no longer offered to new contracts (existing contracts are unaffected until a switch occurs).
`minimum_contract_term`	The minimum period (in months) a customer must remain on this product before requesting a switch or termination.
`contract_notice_period`	The advance notice required before termination or a product switch, expressed as a number plus a unit: `m` (months) or `w` (weeks). For example, `"2m"` means two months’ notice.

Tariff types

Lumenaza supports two tariff models, each with different required input parameters.

Fix Price
Spot Price

A fixed working price that does not change with market conditions during the validity period.Required parameters when requesting fix-price offers:

Parameter	Description
`zip_code`	The postal code of the supply point, used to determine network fees.
`consumption`	Estimated annual consumption in kWh, used to calculate the total annual cost.

Fix-price products give customers predictable bills and are typically preferred for residential and small-business contracts.

A variable working price that tracks the wholesale electricity spot market, averaged over a rolling window.Required parameters when requesting spot-price offers:

Parameter	Description
`months_for_average_prices_and_costs`	The number of historical months used to calculate the average spot price shown to the customer.

Spot-price products are suited to customers who are comfortable with price variability and want to benefit from periods of low market prices.

Product validity and contract terms

A product’s valid_from / valid_until window controls when it can be offered — existing contracts already on that product are not automatically terminated when valid_until passes. The minimum_contract_term and contract_notice_period govern when a customer can leave or switch:

Contract signed
      │
      ├──── minimum_contract_term (months) ────┤
      │                                        │
      │                              Earliest point customer
      │                              can switch or terminate
      │
      └── contract_notice_period must be given BEFORE the desired end / switch date

Product start vs. delivery start

These two dates are distinct and independently managed:

Delivery start (preferred_delivery_start on the contract): the date physical energy delivery begins at the meter.
Product start: the date from which the product’s pricing takes effect. This can be set separately via:
PUT /v3/consumers/{userID}/contracts/{contractID}/products/product_start/
This is useful when a pricing plan change needs to take effect on a date that does not coincide with the start of delivery (for example, at the beginning of a new billing month after delivery has already started).

Switching a product

You can move an active contract from one product to another using the switch endpoint:

POST /v3/consumers/{userID}/contracts/{contractID}/product/switch_product/

Rules that apply to a product switch:

Future first-of-month date required

The requested switch date must be the first day of a future month. Mid-month or backdated switches are not permitted.

Minimum contract term must be satisfied

The switch cannot take place before the minimum_contract_term on the current product has elapsed from the contract (or current product) start date.

Notice period must be observed

The switch request must be submitted with enough lead time to satisfy the current product’s contract_notice_period.

Compatibility check

Lumenaza validates whether the requested product switch is permitted. If the transition between the current product and the target product is not allowed (for example, switching between incompatible tariff types), the API returns an error describing the constraint.

Offer calculator

Before registering a customer, you can preview the prices they would pay under any available product using the offer calculator endpoint:

GET /v3/offer_calculator/

Supply the relevant parameters (tariff type, zip_code + consumption for fix-price, or months_for_average_prices_and_costs for spot-price) and the API returns a breakdown of the base fee, working price, and estimated annual cost for each eligible product. Use this to power a price-comparison or sign-up flow in your own application before committing to a contract creation.

Call the offer calculator with your customer’s actual zip code and consumption estimate to ensure the network-fee component of the price is calculated correctly for their grid area.

Get Started

Core Concepts

Guides

Data & Analytics

Products and Tariffs: Pricing in Lumenaza Contracts

Product structure

Tariff types

Product validity and contract terms

Product start vs. delivery start

Switching a product

Offer calculator

​Product structure

​Tariff types

​Product validity and contract terms

​Product start vs. delivery start

​Switching a product

​Offer calculator

Product structure

Tariff types

Product validity and contract terms

Product start vs. delivery start

Switching a product

Offer calculator