Skip to main content
A contract in Lumenaza represents the formal energy delivery (or feed-in) agreement between a customer and the distribution grid operator. It captures everything the grid operator needs to register a new supply point or transfer an existing one: the customer’s identity, the physical location and meter, the desired delivery start date, and the reason for the subscription. Managing contracts correctly — and understanding their lifecycle — is the most important operational task you will perform with the API.

​
Contract identifiers

saas_contract_id must be unique within your sales partner account. Choose an ID that maps directly to your own database primary key or CRM reference to simplify reconciliation.

​
Registration status (reg_status)

Every contract moves through a series of registration statuses that reflect its position in the grid operator’s onboarding process. The primary flow for a new customer is:
Additional statuses:
For most integrations, the statuses you will observe in steady state are closed_join (active) and closed_leave (terminated). The intermediate statuses are managed largely by Lumenaza and the grid operator in the background.

​
Delivery start

preferred_delivery_start is the date on which you want energy delivery to begin. The grid operator may adjust this date slightly during the registration process, so always check the confirmed delivery start returned by the API after registration is complete rather than relying solely on the value you submitted.

​
Market Location (MaLo)

Every contract must be associated with a Market Location, known in German as a Marktlokation (MaLo). This is an 11-digit numeric identifier that uniquely identifies a single supply point within the German energy grid — effectively a standardised address for electricity delivery.
Market Location IDs are assigned by the grid operator for the area. Always verify a MaLo before submitting a contract — an incorrect MaLo will cause the registration to fail or, worse, affect the wrong supply point.

​
Meter ID

The meter_id is the identifier printed on the physical electricity meter at the supply point. Unlike the MaLo (which identifies the location), the Meter ID identifies the specific device. Meters can be replaced, so a supply point may have a different Meter ID over time while keeping the same MaLo.

​
Subscription reasons

When creating a contract, you must provide a subscription reason (subscription_reason) that tells the grid operator why this supply point is being registered:

​
Termination vs. revocation

Contracts can be ended in two fundamentally different ways depending on how far through the lifecycle they are.
Revocation cancels a contract before or shortly after delivery begins, and is available at two points in the lifecycle:
  • open_join: The customer has 14 days from contract creation to revoke without penalty. Contracts in the preceding in_revocation_period status are also eligible — the 14-day window starts at creation.
  • closed_join: Even after the registration is active, revocation is still possible up to 8 days before the confirmed delivery start date.
A revoked contract moves to the revoked status. If a registration message has already been sent to the grid operator, a cancellation is dispatched automatically.
Termination applies to contracts in closed_join (active delivery). A termination ends delivery on a specific future date and triggers a formal leave process with the grid operator. Once processed, the contract moves to closed_leave.Termination respects the contract notice period defined on the assigned product. Submit the termination request before the notice period deadline to ensure the desired end date is honoured.