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

# Orders: Mandatory, Optional, Conditional Fields

## Overview

This document outlines the mandatory and optional fields for the POST /orders endpoint, including conditional requirements based on contract type and reason.

***

## Field Requirement Levels

| Symbol             | Meaning                               |
| ------------------ | ------------------------------------- |
| ✅ **Required**     | Always mandatory                      |
| ⚠️ **Conditional** | Required based on specific conditions |
| ℹ️ **Optional**    | Not required but recommended          |
| ❌ **Excluded**     | Must be null for certain scenarios    |

***

## 1. Top-Level Fields

| Field          | Requirement     | Notes                                                                                                        |
| -------------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
| `tariffKey`    | ✅ **Required**  | Mandatory for order creation and change process                                                              |
| `offerDate`    | ℹ️ **Optional** | Mandatory for Fix Tariffs to ensure accurate pricing for the contract                                        |
| `campaignCode` | ℹ️ **Optional** | If a promotion is running and a campaignCode exists, relevant campaign conditions will apply to the contract |

***

## 2. User Account (`userAccount`)

| Field          | Requirement        | Notes                                                                                          |
| -------------- | ------------------ | ---------------------------------------------------------------------------------------------- |
| `emailAddress` | ✅ **Required**     | Mandatory for order creation and change process                                                |
| `phoneNumber`  | ℹ️ **Optional**    |                                                                                                |
| `password`     | ⚠️ **Conditional** | Transmit `null`, customer is auto-enrolled in password set email flow                          |
| `firstName`    | ⚠️ **Conditional** | **B2C**: Required for change process<br />**B2B**: Can be `null` if `businessName` is provided |
| `lastName`     | ⚠️ **Conditional** | **B2C**: Required for change process<br />**B2B**: Can be `null` if `businessName` is provided |
| `businessName` | ⚠️ **Conditional** | **B2B**: Required for change process if `firstName` and `lastName` are `null`                  |
| `gender`       | ℹ️ **Optional**    |                                                                                                |
| `dateOfBirth`  | ℹ️ **Required**    | Mandatory for order creation and change process                                                |

***

## 3. Contract (`contract`)

### 3.1 Contract Top-Level

| Field                 | Requirement        | Notes                                                                                                                                             |
| --------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `externalId`          | ℹ️ **Optional**    | Partner's internal reference                                                                                                                      |
| `type`                | ✅ **Required**     | Required for change process (B2C & B2B)<br />Values: `Personal`, `Business`                                                                       |
| `industry`            | ⚠️ **Conditional** | **B2B**: Required for Business contracts<br />**B2C**: Must be `null`<br />Example values: `ElectricalEquipment`, `Manufacturing`, `Retail`, etc. |
| `legalStructure`      | ⚠️ **Conditional** | **B2B**: Required for Business contracts<br />**B2C**: Must be `null`<br />Example values: `GmbH`, `AG`, `KG`, `OHG`, etc.                        |
| `transactionDateTime` | ℹ️ **Optional**    |                                                                                                                                                   |

### 3.2 Delivery Address (`contract.deliveryAddress`)

| Field          | Requirement        | Notes                                                                                          |
| -------------- | ------------------ | ---------------------------------------------------------------------------------------------- |
| `title`        | ℹ️ **Optional**    |                                                                                                |
| `firstName`    | ⚠️ **Conditional** | **B2C**: Required for change process<br />**B2B**: Can be `null` if `businessName` is provided |
| `lastName`     | ⚠️ **Conditional** | **B2C**: Required for change process<br />**B2B**: Can be `null` if `businessName` is provided |
| `businessName` | ⚠️ **Conditional** | **B2B**: Required for change process if `firstName` and `lastName` are `null`                  |
| `gender`       | ℹ️ **Optional**    |                                                                                                |
| `extension`    | ℹ️ **Optional**    |                                                                                                |
| `streetName`   | ✅ **Required**     | Required for change process (B2C & B2B)                                                        |
| `houseNumber`  | ✅ **Required**     | Required for change process (B2C & B2B)                                                        |
| `city`         | ✅ **Required**     | Required for change process (B2C & B2B)                                                        |
| `postCode`     | ✅ **Required**     | Required for change process (B2C & B2B)                                                        |
| `countryCode`  | ✅ **Required**     | Required for change process (B2C & B2B)<br />Expected: `DE`                                    |

### 3.3 Billing Address (`contract.billingAddress`)

| Field            | Requirement     | Notes                                                                                                                      |
| ---------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `billingAddress` | ℹ️ **Optional** | If `null`, billing address = delivery address, all data fields must be transmitted if it deviates from the deliveryAddress |

### 3.4 Bank Details (`contract.bankDetails`)

| Field                    | Requirement        | Notes                                              |
| ------------------------ | ------------------ | -------------------------------------------------- |
| `hasAcceptedDirectDebit` | ⚠️ **Conditional** | Required if direct debit payment method requested  |
| `accountHolder`          | ⚠️ **Conditional** | **Required** if `hasAcceptedDirectDebit` is `true` |
| `iban`                   | ⚠️ **Conditional** | **Required** if `hasAcceptedDirectDebit` is `true` |
| `bic`                    | ℹ️ **Optional**    |                                                    |
| `bankName`               | ℹ️ **Optional**    |                                                    |

<Warning>
  If bank transfer (Überweisung) is selected as the payment method, then the ´bankDetails´ object should be null
</Warning>

***

## 4. Delivery Details (`contract.deliveryDetails`)

### 4.1 Meter & Location Identifiers

| Field            | Requirement     | Notes                                                                                                             |
| ---------------- | --------------- | ----------------------------------------------------------------------------------------------------------------- |
| `meterNumber`    | ✅ **Required**  | Required for change process (B2C & B2B)                                                                           |
| `maLoIdentifier` | ℹ️ **Optional** | **Recommended**: Increases speed at which change process progresses (e.g., invalid address, invalid meter number) |
| `meLoIdentifier` | ℹ️ **Optional** |                                                                                                                   |

### 4.2 Contract Reason & Dates

| Field            | Requirement    | Notes                                             |
| ---------------- | -------------- | ------------------------------------------------- |
| `contractReason` | ✅ **Required** | Values: `ChangeOfSupplier`, `NewDeliveryLocation` |

**`Conditional Fields Based on contractReason:`**

#### If `contractReason` = `ChangeOfSupplier` (Supplier Switch)

| Field                       | Requirement    | Notes                                   |
| --------------------------- | -------------- | --------------------------------------- |
| `desiredTransitionDate`     | ✅ **Required** | Required for change process (B2C & B2B) |
| `moveInDate`                | ❌ **Excluded** | Must be `null`                          |
| `previousSelfCancelledDate` | ✅ **Required** | Required for change process (B2C & B2B) |

#### If `contractReason` = `NewDeliveryLocation` (Move-In)

| Field                       | Requirement    | Notes                                   |
| --------------------------- | -------------- | --------------------------------------- |
| `desiredTransitionDate`     | ❌ **Excluded** | Must be `null`                          |
| `moveInDate`                | ✅ **Required** | Required for change process (B2C & B2B) |
| `previousSelfCancelledDate` | ❌ **Excluded** | Must be `null`                          |

### 4.3 Previous Supplier & Consumption

| Field                          | Requirement    | Notes                                                                         |
| ------------------------------ | -------------- | ----------------------------------------------------------------------------- |
| `previousSupplierCode`         | ✅ **Required** | Required for change process (B2C & B2B)<br />13-digit supplier code           |
| `previousAnnualConsumptionKwh` | ✅ **Required** | Required for order creation and change process - Value must be above 1000 kWh |

### 4.4 Capabilities (`contract.deliveryDetails.capabilities`)

| Field                | Requirement    | Notes                                          |
| -------------------- | -------------- | ---------------------------------------------- |
| `hasElectricVehicle` | ✅ **Required** | Required for order creation and change process |
| `hasSmartMeter`      | ✅ **Required** | Required for order creation and change process |
| `hasHeatPump`        | ✅ **Required** | Required for order creation and change process |

***

## 5. Agreements (`contract.agreements`)

| Field                | Requirement    | Notes                                                              |
| -------------------- | -------------- | ------------------------------------------------------------------ |
| `termsAndConditions` | ✅ **Required** | Required for order creation and change process<br />Must be `true` |
| `privacyPolicy`      | ✅ **Required** | Required for order creation and change process<br />Must be `true` |
| `revocationPolicy`   | ✅ **Required** | Required for order creation and change process<br />Must be `true` |

***

## Quick Reference: Contract Reason Decision Tree

```
contractReason?
├── ChangeOfSupplier (Supplier Switch)
│   ├── ✅ desiredTransitionDate (required)
│   ├── ✅ previousSelfCancelledDate (required)
│   └── ❌ moveInDate (must be null)
│
└── NewDeliveryLocation (Move-In)
    ├── ✅ moveInDate (required)
    ├── ❌ desiredTransitionDate (must be null)
    └── ❌ previousSelfCancelledDate (must be null)
```

***

## B2C vs B2B Decision Tree

```
Contract Type?
├── B2C (Personal)
│   ├── userAccount.firstName (required)
│   ├── userAccount.lastName (required)
│   ├── deliveryAddress.firstName (required)
│   ├── deliveryAddress.lastName (required)
│   ├── contract.industry (must be null)
│   ├── contract.legalStructure (must be null)
│   └── businessName fields must be null
│
└── B2B (Business)
    ├── userAccount.businessName (required)
    ├── deliveryAddress.businessName (required)
    ├── contract.industry (required)
    ├── contract.legalStructure (required)
    └── firstName/lastName fields can be null
```

## Direct Debit vs Bank Transfer Decision Tree

```
Payment Type?
├── Direct Debit (SEPA / Lastschrift)
│   ├── bankDetails.hasAcceptedDirectDebit (required)
│   ├── bankDetails.accountHolder (required)
│   ├── bankDetails.iban (required)
│   ├── bankDetails.bic (optional)
│   └── bankDetails.bankName (optional)
│
└── Bank Transfer (Überweisung)
    └── bankDetails object must be null
```

***

## Validation Summary

### Always Required (All Scenarios)

* `tariffKey`
* `userAccount.emailAddress`
* `contract.type`
* `contract.deliveryAddress` (full address: street, house number, city, postcode, country)
* `contract.bankDetails.hasAcceptedDirectDebit`
* `contract.deliveryDetails.meterNumber`
* `contract.deliveryDetails.previousSupplierCode`
* `contract.deliveryDetails.previousAnnualConsumptionKwh`
* `contract.deliveryDetails.capabilities` (all three flags)
* `contract.agreements` (all three must be `true`)

### Conditionally Required

* **Bank details** (if direct debit accepted):
  * `accountHolder`
  * `iban`
* **B2C contracts**:
  * `userAccount.firstName`
  * `userAccount.lastName`
  * `deliveryAddress.firstName`
  * `deliveryAddress.lastName`
* **B2B contracts**:
  * `userAccount.businessName`
  * `deliveryAddress.businessName`
  * `contract.industry`
  * `contract.legalStructure`
* **ChangeOfSupplier**:
  * `desiredTransitionDate`
  * `previousSelfCancelledDate`
* **NewDeliveryLocation**:
  * `moveInDate`

### Recommended (Optional but Helpful)

* `contract.deliveryDetails.maLoIdentifier` - Can prevent delays due to invalid addresses or meter numbers

***

## Example Payloads

### Example 1: B2C Supplier Change

```json theme={null}
{
  "tariffKey": "RabotSmart",
  "offerDate": "2025-08-22",
  "userAccount": {
    "emailAddress": "j.doe@example.tld",
    "phoneNumber": "+491234567890",
    "password": "SomeExamplePassword987.",
    "firstName": "Max",
    "lastName": "Mustermann",
    "businessName": null,
    "gender": "Male",
    "dateOfBirth": "2019-08-24"
  },
  "contract": {
    "type": "Private",
    "deliveryAddress": {
      "firstName": "Thomas",
      "lastName": "Mustermann",
      "businessName": null,
      "streetName": "Grüner Weg",
      "houseNumber": "42",
      "city": "Berlin",
      "postCode": "14109",
      "countryCode": "DE"
    },
    "billingAddress": null,
    "bankDetails": {
      "accountHolder": "Thomas Heinrich Mustermann",
      "iban": "DE89370400440532013000",
      "hasAcceptedDirectDebit": true
    },
    "contractReason": "ChangeOfSupplier",
    "deliveryDetails": {
      "meterNumber": "123456789",
      "maLoIdentifier": "99987999749",
      "desiredTransitionDate": "2024-05-01",
      "moveInDate": null,
      "previousSelfCancelledDate": "2024-04-22",
      "previousSupplierCode": "9979250000006",
      "previousAnnualConsumptionKwh": 2600,
      "capabilities": {
        "hasElectricVehicle": false,
        "hasSmartMeter": true,
        "hasHeatPump": true
      }
    },
    "agreements": {
      "termsAndConditions": true,
      "privacyPolicy": true,
      "revocationPolicy": true
                  },
"transactionDateTime": "2024-04-01 00:00:00",
"industry": null,
"legalStructure": null
    },
"campaignCode": "string"
}
```

### Example 2: B2B Move-In

```json theme={null}
{
  "tariffKey": "RabotSmart",
  "userAccount": {
    "emailAddress": "info@example-business.de",
    "firstName": null,
    "lastName": null,
    "businessName": "Example GmbH"
  },
  "contract": {
    "type": "Business",
    "deliveryAddress": {
      "firstName": null,
      "lastName": null,
      "businessName": "Example GmbH",
      "streetName": "Hauptstraße",
      "houseNumber": "100",
      "city": "München",
      "postCode": "80331",
      "countryCode": "DE"
    },
    "bankDetails": {
      "accountHolder": "Example GmbH",
      "iban": "DE89370400440532013000",
      "hasAcceptedDirectDebit": true
    },
    "contractReason": "NewDeliveryLocation",
    "deliveryDetails": {
      "meterNumber": "987654321",
      "desiredTransitionDate": null,
      "moveInDate": "2024-06-01",
      "previousSelfCancelledDate": null,
      "previousSupplierCode": "9979250000006",
      "previousAnnualConsumptionKwh": 50000,
      "capabilities": {
        "hasElectricVehicle": false,
        "hasSmartMeter": true,
        "hasHeatPump": false
      }
    },
    "agreements": {
      "termsAndConditions": true,
      "privacyPolicy": true,
      "revocationPolicy": true
    },
    "transactionDateTime": "2024-04-01 00:00:00",
"industry": "ElectricalEquipment",
"legalStructure": "GmbH"
    },
"campaignCode": "string"
}
```

***

## Common Validation Errors

| Error Scenario                      | Cause                                                 | Solution                                                |
| ----------------------------------- | ----------------------------------------------------- | ------------------------------------------------------- |
| Missing mandatory field             | Required field is `null` or omitted                   | Review requirement tables above                         |
| Invalid contract reason combination | `moveInDate` provided with `ChangeOfSupplier`         | Follow contract reason decision tree                    |
| Missing bank details                | Direct debit accepted but IBAN/account holder missing | Provide both fields when `hasAcceptedDirectDebit: true` |
| B2C/B2B mismatch                    | Business name provided with personal contract type    | Align `contract.type` with name fields                  |
| Invalid address                     | Address cannot be found in system                     | Provide `maLoIdentifier` to improve matching            |

***

## Questions or Concerns?

Feel free to speak with our [Integration Management Team](mailto:j.ohara@rabot.energy) or alternatively, ask our built-in AI assistant, Rabotini 🤖 (several languages supported).