Manage Energy Contracts in Lumenaza

This guide covers the full lifecycle of energy contracts in Lumenaza — from listing and inspecting contracts through to switching products, updating installments, terminating, revoking, and linking related contracts. Base URLs

Environment	URL
Production	`https://api.lumenaza.de/`
Test	`https://api.test.lumenaza.de/`

All requests require an Authorization: Bearer <token> header.

1. List Contracts

Retrieve all contract IDs associated with a consumer or producer.

curl -X GET "https://api.lumenaza.de/v3/consumers/{userID}/contracts/" \
  -H "Authorization: Bearer <token>"

Response

{
  "contract_ids": [
    "contract_abc123",
    "contract_def456"
  ]
}

For producers, replace /consumers/ with /producers/ in the path.

2. Get Contract Details

Fetch the full details of a specific contract.

curl -X GET "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/" \
  -H "Authorization: Bearer <token>"

Key response fields

Field	Description
`saas_contract_id`	Your internal contract identifier (as supplied at registration)
`reg_status`	Current registration status (e.g., `active`, `pending`)
`preferred_delivery_start`	Requested start date for energy delivery
`annual_consumption`	Expected annual consumption in kWh
`meter_id`	Associated meter identifier
`payment_method`	Payment method on file (e.g., `sepa_direct_debit`)
`bank_data_iban`	IBAN used for payment (masked)

Example response

{
  "saas_contract_id": "contract_abc123",
  "reg_status": "active",
  "preferred_delivery_start": "2024-03-01",
  "annual_consumption": 3500,
  "meter_id": "DE0001234567890001",
  "payment_method": "sepa_direct_debit",
  "bank_data_iban": "DE89***********4321"
}

3. Switch a Product

Move a contract to a different product (tariff) from a future date. This endpoint is only available for contracts in closed_join status. The valid_from date must be the first day of a future month.

curl -X POST "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/product/switch_product/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "green-energy-plus-2024",
    "valid_from": "2024-05-01"
  }'

Request body

Field	Type	Required	Description
`product_name`	string	✅	The identifier of the target product
`valid_from`	date	✅	Switch date — must be the first of a future month (e.g., `2024-05-01`)

Example response

{
  "saas_contract_id": "contract_abc123",
  "product_name": "green-energy-plus-2024",
  "valid_from": "2024-05-01"
}

4. Update Installment Amount

Adjust the regular installment (advance payment) for a contract. You can specify the amount either in cents per month or in kWh per year — Lumenaza will calculate the equivalent.

Cents per month
kWh per year

curl -X POST "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/trigger_installment_update/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "unit": "cent_per_month",
    "amount": 8500
  }'

This sets the monthly installment to €85.00.

curl -X POST "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/trigger_installment_update/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "unit": "kwh_per_year",
    "amount": 3500
  }'

This sets the installment based on an expected annual consumption of 3,500 kWh.

5. Terminate a Contract

Submit a termination request for a contract.

curl -X POST "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/terminate/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "termination_reason": "E03",
    "contract_end_date": "2024-06-30"
  }'

Request body

Field	Type	Required	Description
`termination_reason`	string	✅	Reason code (see table below)
`contract_end_date`	date	✅	Requested end date for the contract

Termination reason codes

Code	Meaning
`E01`	Customer is moving
`E03`	Customer is switching supplier
`ZT4`	Special termination reason ZT4
`ZT5`	Special termination reason ZT5

Successful response

{
  "detail": "contract successfully terminated"
}

If the requested date is too early (HTTP 400)

{
  "detail": "Termination date is too early.",
  "possible_termination_date": "2024-07-31"
}

Use the returned possible_termination_date value to retry the request with a valid date.

6. Revoke a Contract

Cancel a contract registration during the permitted revocation window.

curl -X POST "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/revoke/" \
  -H "Authorization: Bearer <token>"

Revocation is only possible within the revocation window:

Within 14 days of the contract registration date, or
At least 8 days before the scheduled delivery start date.

Requests outside this window will be rejected.

7. Link Contracts via Relationships

Associate two contracts with each other to model real-world relationships such as shared billing, joint termination, or private/business complements.

curl -X POST "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/relationships/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "relationship_type": "contract_is_paid_by",
    "related_contract_id": "contract_def456"
  }'

Supported relationship types

Relationship type	Description
`contract_is_paid_by`	This contract’s invoices are paid by another contract
`contract_is_terminated_together_with`	Both contracts will be terminated simultaneously
`is_private_complement`	This contract is the private-use complement of a business contract

Get Started

Core Concepts

Guides

Data & Analytics

Manage Energy Contracts in Lumenaza

Manage Energy Contracts in Lumenaza

1. List Contracts

2. Get Contract Details

3. Switch a Product

4. Update Installment Amount

5. Terminate a Contract

6. Revoke a Contract

7. Link Contracts via Relationships

​Manage Energy Contracts in Lumenaza

​1. List Contracts

​2. Get Contract Details

​3. Switch a Product

​4. Update Installment Amount

​5. Terminate a Contract

​6. Revoke a Contract

​7. Link Contracts via Relationships

Manage Energy Contracts in Lumenaza

1. List Contracts

2. Get Contract Details

3. Switch a Product

4. Update Installment Amount

5. Terminate a Contract

6. Revoke a Contract

7. Link Contracts via Relationships