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 B2B: Can be `null` if `businessName` is provided
`lastName`	⚠️ Conditional	B2C: Required for change process 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) Values: `Personal`, `Business`
`industry`	⚠️ Conditional	B2B: Required for Business contracts B2C: Must be `null` Example values: `ElectricalEquipment`, `Manufacturing`, `Retail`, etc.
`legalStructure`	⚠️ Conditional	B2B: Required for Business contracts B2C: Must be `null` 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 B2B: Can be `null` if `businessName` is provided
`lastName`	⚠️ Conditional	B2C: Required for change process 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) 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
`accountHolder`	⚠️ Conditional	Required if `hasAcceptedDirectDebit` is `true`
`iban`	⚠️ Conditional	Required if `hasAcceptedDirectDebit` is `true`
`bic`	ℹ️ Optional
`bankName`	ℹ️ Optional
`hasAcceptedDirectDebit`	✅ Required	Required for change process (B2C & B2B)

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) 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 Must be `true`
`privacyPolicy`	✅ Required	Required for order creation and change process Must be `true`
`revocationPolicy`	✅ Required	Required for order creation and change process 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

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

{
  "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

{
  "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

Introduction

Get Started

Quickstart

Guides

Updates

API reference

Orders: Mandatory, Optional, Conditional Fields

Overview

Field Requirement Levels

1. Top-Level Fields

2. User Account (`userAccount`)

3. Contract (`contract`)

3.1 Contract Top-Level

3.2 Delivery Address (`contract.deliveryAddress`)

3.3 Billing Address (`contract.billingAddress`)

3.4 Bank Details (`contract.bankDetails`)

4. Delivery Details (`contract.deliveryDetails`)

4.1 Meter & Location Identifiers

4.2 Contract Reason & Dates

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

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

4.3 Previous Supplier & Consumption

4.4 Capabilities (`contract.deliveryDetails.capabilities`)

5. Agreements (`contract.agreements`)

Quick Reference: Contract Reason Decision Tree

B2C vs B2B Decision Tree

Validation Summary

Always Required (All Scenarios)

Conditionally Required

Recommended (Optional but Helpful)

Example Payloads

Example 1: B2C Supplier Change

Example 2: B2B Move-In

Common Validation Errors

Introduction

Get Started

Quickstart

Guides

Updates

API reference

​Overview

​Field Requirement Levels

​1. Top-Level Fields

​2. User Account (userAccount)

​3. Contract (contract)

​3.1 Contract Top-Level

​3.2 Delivery Address (contract.deliveryAddress)

​3.3 Billing Address (contract.billingAddress)

​3.4 Bank Details (contract.bankDetails)

​4. Delivery Details (contract.deliveryDetails)

​4.1 Meter & Location Identifiers

​4.2 Contract Reason & Dates

​If contractReason = ChangeOfSupplier (Supplier Switch)

​If contractReason = NewDeliveryLocation (Move-In)

​4.3 Previous Supplier & Consumption

​4.4 Capabilities (contract.deliveryDetails.capabilities)

​5. Agreements (contract.agreements)

​Quick Reference: Contract Reason Decision Tree

​B2C vs B2B Decision Tree

​Validation Summary

​Always Required (All Scenarios)

​Conditionally Required

​Recommended (Optional but Helpful)

​Example Payloads

​Example 1: B2C Supplier Change

​Example 2: B2B Move-In

​Common Validation Errors

Overview

Field Requirement Levels

1. Top-Level Fields

2. User Account (`userAccount`)

3. Contract (`contract`)

3.1 Contract Top-Level

3.2 Delivery Address (`contract.deliveryAddress`)

3.3 Billing Address (`contract.billingAddress`)

3.4 Bank Details (`contract.bankDetails`)

4. Delivery Details (`contract.deliveryDetails`)

4.1 Meter & Location Identifiers

4.2 Contract Reason & Dates

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

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

4.3 Previous Supplier & Consumption

4.4 Capabilities (`contract.deliveryDetails.capabilities`)

5. Agreements (`contract.agreements`)

Quick Reference: Contract Reason Decision Tree

B2C vs B2B Decision Tree

Validation Summary

Always Required (All Scenarios)

Conditionally Required

Recommended (Optional but Helpful)

Example Payloads

Example 1: B2C Supplier Change

Example 2: B2B Move-In

Common Validation Errors