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

# Register an Electricity Consumer

> Step-by-step guide to validating delivery addresses, previewing pricing, and registering an electricity consumer via the Lumenaza v3 API.

This guide walks you through the full lifecycle of onboarding a new electricity consumer — from address validation and price preview all the way to confirming registration status and handling revocations.

**Base URL:** `https://api.lumenaza.de/` (use `https://api.test.lumenaza.de/` for sandbox testing)

All requests require an `Authorization` header:

```http theme={null}
Authorization: Bearer <token>
```

***

<Steps>
  <Step title="Validate the Delivery Address (Recommended)">
    Before submitting a registration, validate the delivery address and confirm the earliest possible delivery start date. This step is optional but strongly recommended to avoid rejected registrations.

    ### Check Earliest Delivery Start

    Use the `preferred_delivery_start` endpoint to determine the earliest date Lumenaza can begin delivery at the given address.

    ```http theme={null}
    GET /v3/validation/preferred_delivery_start/?zip_code=10115&street=Unter+den+Linden&house_number=1
    ```

    **Example response:**

    ```json theme={null}
    {
      "preferred_delivery_start": "2024-03-01"
    }
    ```

    <Warning>
      The `preferred_delivery_start` date must be **at least 2 weeks in the future** for most registrations. For `E03` (provider switch) registrations only, dates up to **6 weeks in the past** are accepted. Always check this value before submitting the registration to avoid validation errors.
    </Warning>

    ### Validate a Market Location ID

    If you have a market location identifier (Marktlokations-ID), validate it before use:

    ```http theme={null}
    GET /v3/validation/market_location/?market_location_identifier=52173487564
    ```

    **Example response:**

    ```json theme={null}
    {
      "is_valid": true,
      "market_location_identifier": "52173487564",
      "address": {
        "street": "Unter den Linden",
        "house_number": "1",
        "zip_code": "10115",
        "city": "Berlin"
      }
    }
    ```
  </Step>

  <Step title="Preview Pricing (Optional)">
    Before registering, you can fetch a price estimate for a specific tariff, postal code, and annual consumption. This helps surface pricing to the end customer before they commit.

    ```http theme={null}
    GET /v3/offer_calculator/?tariff_name=YOUR_TARIFF&zip_code=10115&consumption=3500
    ```

    | Query Parameter | Type | Description |
    | - | - | - |
    | `tariff_name` | string | The tariff identifier configured in your account |
    | `zip_code` | string | Five-digit German postal code |
    | `consumption` | integer | Estimated annual consumption in kWh |

    **Example response:**

    ```json theme={null}
    {
      "offer_item_price_results": [
        {
          "name": "Base price",
          "price_net": 8.90,
          "price_gross": 10.59,
          "unit": "EUR/month"
        },
        {
          "name": "Energy price",
          "price_net": 0.28,
          "price_gross": 0.33,
          "unit": "EUR/kWh"
        }
      ],
      "total_price_results": {
        "monthly_net": 86.23,
        "monthly_gross": 102.61,
        "annual_net": 1034.76,
        "annual_gross": 1231.36
      }
    }
    ```

    Use `offer_item_price_results` to display a line-item breakdown and `total_price_results` for a summary view.
  </Step>

  <Step title="Register the Consumer">
    Submit the consumer's details to create a new contract in Lumenaza.

    ```http theme={null}
    POST /v3/consumers/create/
    Content-Type: application/json
    Authorization: Bearer <token>
    ```

    ### Key Parameters

    <ParamField body="first_name" type="string" required>
      Consumer's first name.
    </ParamField>

    <ParamField body="last_name" type="string" required>
      Consumer's last name.
    </ParamField>

    <ParamField body="email" type="string" required>
      Consumer's email address. Used for contract communications.
    </ParamField>

    <ParamField body="salutation" type="string" required>
      Consumer's salutation. Must be one of: `Frau`, `Herr`, `Eheleute`, `Divers`.
    </ParamField>

    <ParamField body="is_business" type="boolean" required>
      Set to `true` for business customers, `false` for private consumers.
    </ParamField>

    <ParamField body="deliv_address_street" type="string" required>
      Street name of the delivery address.
    </ParamField>

    <ParamField body="deliv_address_house_number" type="string" required>
      House number of the delivery address. Maximum 5 characters.
    </ParamField>

    <ParamField body="deliv_address_zipcode" type="string" required>
      Five-digit postal code of the delivery address. Maximum 5 characters.
    </ParamField>

    <ParamField body="deliv_address_city" type="string" required>
      City of the delivery address.
    </ParamField>

    <ParamField body="annual_consumption" type="integer" required>
      Estimated annual electricity consumption in kWh.
    </ParamField>

    <ParamField body="subscription_reason" type="string" required>
      Reason for the subscription. One of:

      * `E01` — New move-in
      * `E02` — New connection
      * `E03` — Provider switch
    </ParamField>

    <ParamField body="tariff_type" type="string" required>
      Tariff identifier to assign to this consumer.
    </ParamField>

    <ParamField body="previous_provider" type="string">
      Required when `subscription_reason` is `E03`. The BDEW code or name of the consumer's current electricity provider.
    </ParamField>

    <ParamField body="saas_customer_id" type="string">
      Your internal customer identifier. Maximum 32 characters. Must be unique across all consumers in your account.
    </ParamField>

    <ParamField body="saas_contract_id" type="string">
      Your internal contract identifier. Maximum 64 characters.
    </ParamField>

    <ParamField body="payment_method" type="string">
      Payment method for the contract, e.g. `sepa_direct_debit` or `bank_transfer`.
    </ParamField>

    <ParamField body="bank_data_iban" type="string">
      Consumer's IBAN for SEPA direct debit payments.
    </ParamField>

    <ParamField body="bank_data_bic" type="string">
      BIC/SWIFT code associated with `bank_data_iban`.
    </ParamField>

    <ParamField body="sepa_date" type="string">
      Date of the SEPA mandate signature (ISO 8601 format: `YYYY-MM-DD`).
    </ParamField>

    <Note>
      `saas_customer_id` must be **unique** within your Lumenaza account. If you submit a duplicate value, the API will return a validation error. Use a stable internal ID (e.g. your CRM's customer UUID) rather than a mutable identifier.
    </Note>

    ### Example Request Body

    ```json theme={null}
    {
      "first_name": "Maria",
      "last_name": "Müller",
      "email": "maria.mueller@example.com",
      "salutation": "Frau",
      "is_business": false,
      "deliv_address_street": "Unter den Linden",
      "deliv_address_house_number": "1",
      "deliv_address_zipcode": "10115",
      "deliv_address_city": "Berlin",
      "annual_consumption": 3500,
      "subscription_reason": "E03",
      "previous_provider": "Vattenfall",
      "tariff_type": "green_basic_2024",
      "saas_customer_id": "crm-customer-00123",
      "saas_contract_id": "crm-contract-00456",
      "payment_method": "sepa_direct_debit",
      "bank_data_iban": "DE89370400440532013000",
      "bank_data_bic": "COBADEFFXXX",
      "sepa_date": "2024-01-15"
    }
    ```

    ### Success Response

    **HTTP 201 Created**

    ```json theme={null}
    {
      "consumer_id": "usr_4f9a23bc1e",
      "contract_id": "ctr_7d81e04c2a"
    }
    ```

    Store both `consumer_id` and `contract_id` — they are required for all subsequent operations on this consumer.
  </Step>

  <Step title="Confirm Registration Status">
    After registration, poll the contract endpoint to track the registration lifecycle.

    ```http theme={null}
    GET /v3/consumers/{userID}/contracts/{contractID}/
    Authorization: Bearer <token>
    ```

    Replace `{userID}` with the `consumer_id` and `{contractID}` with the `contract_id` returned in Step 3.

    **Example response:**

    ```json theme={null}
    {
      "contract_id": "ctr_7d81e04c2a",
      "consumer_id": "usr_4f9a23bc1e",
      "reg_status": "open_join",
      "tariff_type": "green_basic_2024",
      "deliv_address_street": "Unter den Linden",
      "deliv_address_house_number": "1",
      "deliv_address_zipcode": "10115",
      "deliv_address_city": "Berlin",
      "annual_consumption": 3500,
      "delivery_start": "2024-03-01",
      "created_at": "2024-01-15T10:32:00Z"
    }
    ```

    | `reg_status` Value | Meaning |
    | - | - |
    | `open_join` | Registration submitted, awaiting grid operator processing |
    | `closed_join` | Grid operator confirmed; delivery is active |
    | `rejected` | Registration rejected by the grid operator |
    | `revoked` | Contract was revoked during the open window |

    Typically, `open_join` transitions to `closed_join` within a few business days once the grid operator processes the switch.
  </Step>

  <Step title="Handle the Revocation Window">
    While a contract is in `open_join` status, it can be revoked within **14 days** of the registration date. This is the standard cancellation window before delivery is confirmed.

    ```http theme={null}
    POST /v3/consumers/{userID}/contracts/{contractID}/revoke/
    Authorization: Bearer <token>
    ```

    **Example response:**

    ```json theme={null}
    {
      "contract_id": "ctr_7d81e04c2a",
      "consumer_id": "usr_4f9a23bc1e",
      "reg_status": "revoked",
      "revoked_at": "2024-01-20T14:05:00Z"
    }
    ```

    After a successful revocation, the `reg_status` transitions to `revoked` and the contract is closed. No delivery will take place.

    <Warning>
      Revocation is only possible while the contract is in `open_join` status. Once the contract transitions to `closed_join`, it cannot be revoked through this endpoint — contact Lumenaza support for assistance with active contracts.
    </Warning>
  </Step>
</Steps>

***

## Next Steps

* **Retrieve invoices:** Use `GET /v3/consumers/{userID}/invoices/` to fetch billing documents.
* **Update consumer data:** Use `PATCH /v3/consumers/{userID}/` to update contact or address information.
* **Register a producer:** If your customer also generates electricity, see [Register a Renewable Energy Producer](/guides/register-producer).


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