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

# Manage Energy Contracts in Lumenaza

> List, inspect, switch products, update installments, terminate, revoke, and link energy contracts using the Lumenaza API.

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

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

**Response**

```json theme={null}
{
  "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.

```bash theme={null}
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**

```json theme={null}
{
  "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.

```bash theme={null}
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**

```json theme={null}
{
  "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.

<Tabs>
  <Tab title="Cents per month">
    ```bash theme={null}
    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**.
  </Tab>

  <Tab title="kWh per year">
    ```bash theme={null}
    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**.
  </Tab>
</Tabs>

***

## 5. Terminate a Contract

Submit a termination request for a contract.

```bash theme={null}
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**

```json theme={null}
{
  "detail": "contract successfully terminated"
}
```

**If the requested date is too early (HTTP 400)**

```json theme={null}
{
  "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.

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

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

***

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

```bash theme={null}
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 |


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