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
`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

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

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

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

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

Questions or Concerns?

Feel free to speak with our Integration Management Team or alternatively, ask our built-in AI assistant, Rabotini 🤖 (several languages supported).

​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

​Direct Debit vs Bank Transfer 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

​Questions or Concerns?

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

Direct Debit vs Bank Transfer 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

Questions or Concerns?