> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumenaza.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Products and Tariffs: Pricing in Lumenaza Contracts

> Understand how pricing plans (products) attach to contracts in Lumenaza, including tariff types, validity periods, contract terms, and product switching.

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.

<Tabs>
  <Tab title="Fix 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.
  </Tab>

  <Tab title="Spot Price">
    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.
  </Tab>
</Tabs>

## 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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Notice period must be observed">
    The switch request must be submitted with enough lead time to satisfy the current product's `contract_notice_period`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

<Tip>
  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.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.