Orders: Mandatory, Optional, Conditional Fields

Overview

This guide explains which fields of the POST /orders request body are mandatory, optional or conditional, depending on the contract type (B2C or B2B), the contract reason (supplier change or move-in) and the payment method. A field can be needed at one of two stages:

Stage	What it means
Order creation	The API validates the request when it is submitted. If one of these fields is missing or invalid, the order is rejected and not created.
Change process	The order is created, but these fields are needed to register the customer with the grid operator and start supply. If one is missing, the data has to be collected from the customer afterwards, which delays the start of supply.

To get your customers into supply as quickly as possible, transmit every field marked for the change process, plus the recommended optional fields, with the initial order.

Field Requirement Levels

Symbol	Meaning
🛑 Required: order creation	The order is rejected if this field is missing or invalid
✅ Required: change process	The order is created, but supply cannot start until this field is provided
⚠️ Conditional	Required only in specific scenarios (see notes)
ℹ️ Optional	Not required; recommended where noted
❌ Must be null	Must be `null` (or omitted) in the given scenario

1. Top-Level Fields

Field	Requirement	Notes
`tariffKey`	🛑 Required: order creation	Must match a tariff key returned by `GET /tariffs` for your client
`offerDate`	ℹ️ Optional	Defaults to today if not provided. Strongly recommended for fixed-price tariffs, so the contract is priced as offered to the customer
`campaignCode`	ℹ️ Optional	If a campaign is running, the relevant campaign conditions are applied to the contract

2. User Account (`userAccount`)

Field	Requirement	Notes
`emailAddress`	🛑 Required: order creation	Used for customer communication and as the login for the RABOT app. If an account with this email address already exists, the new contract is linked to that account
`phoneNumber`	ℹ️ Optional
`password`	ℹ️ Optional	Recommended: transmit `null`. The customer then automatically receives an email to set their own password
`firstName`	⚠️ Conditional	B2C: ✅ Required: change process B2B: Can be `null` if `businessName` is provided
`lastName`	⚠️ Conditional	B2C: ✅ Required: change process B2B: Can be `null` if `businessName` is provided
`businessName`	⚠️ Conditional	B2B: ✅ Required: change process B2C: Must be `null`
`gender`	ℹ️ Optional	Values: `Male`, `Female`, `Other`
`dateOfBirth`	🛑 Required: order creation	Format: `YYYY-MM-DD`

3. Contract (`contract`)

3.1 Contract Top-Level

Field	Requirement	Notes
`type`	🛑 Required: order creation	Values: `Private`, `Business`
`externalId`	ℹ️ Optional	Recommended: your internal reference for the order, useful for reconciliation and support requests
`industry`	⚠️ Conditional	B2B: 🛑 Required: order creation B2C: Must be `null` Value from the `Industries` enum, e.g. `Retail`, `Gastronomy`, `ServicesOther`
`legalStructure`	⚠️ Conditional	B2B: 🛑 Required: order creation B2C: Must be `null` Example values: `GmbH`, `AG`, `KG`, `OHG`
`transactionDateTime`	ℹ️ Optional	Defaults to the current date and time if not provided

Read-only fields of the contract object (number, state, deliveryState, validFromDate, validToDate) are populated by RABOT and should not be transmitted when creating an order.

3.2 Delivery Address (`contract.deliveryAddress`)

Field	Requirement	Notes
`title`	ℹ️ Optional	Academic title, e.g. `Dr.`
`firstName`	⚠️ Conditional	B2C: ✅ Required: change process B2B: Can be `null` if `businessName` is provided
`lastName`	⚠️ Conditional	B2C: ✅ Required: change process B2B: Can be `null` if `businessName` is provided
`businessName`	⚠️ Conditional	B2B: ✅ Required: change process B2C: Must be `null`
`gender`	ℹ️ Optional
`extension`	ℹ️ Optional	Address extension, e.g. `Hinterhaus`
`streetName`	🛑 Required: order creation
`houseNumber`	🛑 Required: order creation
`city`	🛑 Required: order creation
`postCode`	🛑 Required: order creation	Valid German postcode
`countryCode`	🛑 Required: order creation	ISO 3166 alpha-2, expected: `DE`

3.3 Billing Address (`contract.billingAddress`)

Field	Requirement	Notes
`billingAddress`	ℹ️ Optional	If `null`, the delivery address is used for billing. If the billing address differs from the delivery address, transmit the complete object with the same field rules as the delivery address

3.4 Bank Details (`contract.bankDetails`)

The bankDetails object determines the payment method.

Field	Requirement	Notes
`hasAcceptedDirectDebit`	⚠️ Conditional	🛑 Required: order creation, if `bankDetails` is provided. Must be `true` for SEPA direct debit
`iban`	⚠️ Conditional	🛑 Required: order creation, if `bankDetails` is provided
`accountHolder`	⚠️ Conditional	🛑 Required: order creation, if `bankDetails` is provided
`bic`	ℹ️ Optional
`bankName`	ℹ️ Optional

If bank transfer (Überweisung) is selected as the payment method, the bankDetails object must be null.

4. Delivery Details (`contract.deliveryDetails`)

4.1 Meter, Location & Grid Operator Identifiers

Field	Requirement	Notes
`meterNumber`	✅ Required: change process	Meter number of the delivery point
`maLoIdentifier`	ℹ️ Optional	Recommended: 11-digit market location ID. Speeds up the change process and helps avoid delays caused by address or meter number mismatches. If not provided, RABOT retrieves it during the change process
`meLoIdentifier`	ℹ️ Optional	Metering location ID. If not provided, RABOT retrieves it during the change process
`bdewCode`	ℹ️ Optional	New: 13-digit BDEW code of the grid operator serving the delivery point. See BDEW Code of the Grid Operator

4.2 Contract Reason

Field	Requirement	Notes
`contractReason`	🛑 Required: order creation	Values: `ChangeOfSupplier`, `NewDeliveryLocation`

The date fields and the previous supplier depend on the contract reason.

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

Field	Requirement	Notes
`desiredTransitionDate`	🛑 Required: order creation	Desired start of supply with RABOT
`previousSelfCancelledDate`	⚠️ Conditional	Only if the customer has already cancelled their previous contract themselves: the date of that cancellation. Otherwise transmit `null`, and RABOT cancels the previous contract on the customer’s behalf
`previousSupplierCode`	✅ Required: change process	13-digit BDEW code of the previous supplier
`moveInDate`	❌ Must be null

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

Field	Requirement	Notes
`moveInDate`	🛑 Required: order creation	Date the customer moves in to the delivery point
`previousSupplierCode`	ℹ️ Optional	Recommended if known: 13-digit BDEW code of the previous supplier at the delivery point. Can be `null` if the customer does not know it
`desiredTransitionDate`	❌ Must be null
`previousSelfCancelledDate`	❌ Must be null

4.3 Consumption

Field	Requirement	Notes
`previousAnnualConsumptionKwh`	🛑 Required: order creation	Previous annual consumption in kWh. Minimum value: 100 kWh

4.4 Capabilities (`contract.deliveryDetails.capabilities`)

Field	Requirement	Notes
`hasElectricVehicle`	🛑 Required: order creation	`true` or `false`
`hasSmartMeter`	🛑 Required: order creation	`true` or `false`
`hasHeatPump`	🛑 Required: order creation	`true` or `false`

4.5 BDEW Code of the Grid Operator

bdewCode identifies the grid operator (Netzbetreiber) serving the delivery point. It is distinct from previousSupplierCode, which identifies the customer’s previous electricity supplier.

Scenario	Behaviour
`bdewCode` is `null` or omitted	Grid fees and tariff adjustments are resolved by postcode, as before
`bdewCode` is provided and matches the postcode	Grid fees and tariff adjustments are resolved by BDEW code and postcode
`bdewCode` is provided but does not match the postcode	The order is rejected

Only transmit bdewCode if you have a verified value for the delivery point. If you are unsure, transmit null. The same field is available on the tariff calculation request; use the same value in both calls so the order is priced as calculated.

5. Agreements (`contract.agreements`)

Field	Requirement	Notes
`termsAndConditions`	🛑 Required: order creation	Must be `true`
`privacyPolicy`	🛑 Required: order creation	Must be `true`
`revocationPolicy`	🛑 Required: order creation	Must be `true`

6. Response Messages

A successful response returns the customerNumber and contractNumber. It can also include a messages array of non-fatal advisory messages. These do not mean the order failed, but you should log them and review them.

`messages[].type`	Meaning
`LocationIssue`	A location-related condition was detected, e.g. a supplied BDEW code could not be applied and pricing fell back to postcode-based resolution

The messages array is omitted when there are no messages.

Quick Reference: Contract Reason Decision Tree

contractReason?
├── ChangeOfSupplier (Supplier Switch)
│   ├── 🛑 desiredTransitionDate (required: order creation)
│   ├── ✅ previousSupplierCode (required: change process)
│   ├── ⚠️ previousSelfCancelledDate (only if customer self-cancelled, otherwise null)
│   └── ❌ moveInDate (must be null)
│
└── NewDeliveryLocation (Move-In)
    ├── 🛑 moveInDate (required: order creation)
    ├── ℹ️ previousSupplierCode (optional, recommended if known)
    ├── ❌ desiredTransitionDate (must be null)
    └── ❌ previousSelfCancelledDate (must be null)

B2C vs B2B Decision Tree

contract.type?
├── Private (B2C)
│   ├── ✅ userAccount.firstName / lastName (required: change process)
│   ├── ✅ deliveryAddress.firstName / lastName (required: change process)
│   ├── ❌ contract.industry (must be null)
│   ├── ❌ contract.legalStructure (must be null)
│   └── ❌ businessName fields (must be null)
│
└── Business (B2B)
    ├── 🛑 contract.industry (required: order creation)
    ├── 🛑 contract.legalStructure (required: order creation)
    ├── ✅ userAccount.businessName (required: change process)
    ├── ✅ deliveryAddress.businessName (required: change process)
    └── ℹ️ firstName / lastName fields (can be null)

Direct Debit vs Bank Transfer Decision Tree

Payment method?
├── Direct Debit (SEPA Lastschrift)
│   ├── 🛑 bankDetails.hasAcceptedDirectDebit (true)
│   ├── 🛑 bankDetails.iban
│   ├── 🛑 bankDetails.accountHolder
│   ├── ℹ️ bankDetails.bic
│   └── ℹ️ bankDetails.bankName
│
└── Bank Transfer (Überweisung)
    └── ❌ bankDetails object (must be null)

Validation Summary

Stage	Fields
🛑 Order creation: all orders	`tariffKey`, `userAccount.emailAddress`, `userAccount.dateOfBirth`, `contract.type`, `contract.contractReason`, full `contract.deliveryAddress` (street, house number, city, postcode, country), `deliveryDetails.previousAnnualConsumptionKwh`, all three `capabilities` flags, all three `agreements` (must be `true`)
🛑 Order creation: B2B	`contract.industry`, `contract.legalStructure`
🛑 Order creation: direct debit	`bankDetails.hasAcceptedDirectDebit`, `bankDetails.accountHolder`, `bankDetails.iban`
🛑 Order creation: supplier switch	`desiredTransitionDate`
🛑 Order creation: move-in	`moveInDate`
✅ Change process: all orders	`deliveryDetails.meterNumber`
✅ Change process: B2C	`firstName` and `lastName` on `userAccount` and `deliveryAddress`
✅ Change process: B2B	`businessName` on `userAccount` and `deliveryAddress`
✅ Change process: supplier switch	`previousSupplierCode`
⚠️ Conditional	`previousSelfCancelledDate` (only if the customer self-cancelled)
ℹ️ Recommended	`offerDate` (fixed-price tariffs), `externalId`, `maLoIdentifier`, `bdewCode` (only if verified), `previousSupplierCode` (move-in, if known)

Example Payloads

Example 1: B2C Supplier Switch (RABOT cancels the previous contract)

{
  "tariffKey": "RabotSmart",
  "offerDate": "2026-09-29",
  "campaignCode": null,
  "userAccount": {
    "emailAddress": "max.mustermann@example.tld",
    "phoneNumber": "+491234567890",
    "password": null,
    "firstName": "Max",
    "lastName": "Mustermann",
    "businessName": null,
    "gender": "Male",
    "dateOfBirth": "1985-04-12"
  },
  "contract": {
    "externalId": "ORDER-10001",
    "type": "Private",
    "industry": null,
    "legalStructure": null,
    "transactionDateTime": "2026-09-29T10:15:00",
    "deliveryAddress": {
      "firstName": "Max",
      "lastName": "Mustermann",
      "businessName": null,
      "streetName": "Grüner Weg",
      "houseNumber": "42",
      "city": "Berlin",
      "postCode": "14109",
      "countryCode": "DE"
    },
    "billingAddress": null,
    "bankDetails": {
      "accountHolder": "Max Mustermann",
      "iban": "DE89370400440532013000",
      "hasAcceptedDirectDebit": true
    },
    "contractReason": "ChangeOfSupplier",
    "deliveryDetails": {
      "meterNumber": "123456789",
      "maLoIdentifier": "99987999749",
      "desiredTransitionDate": "2026-11-01",
      "moveInDate": null,
      "previousSelfCancelledDate": null,
      "previousSupplierCode": "9979250000006",
      "bdewCode": null,
      "previousAnnualConsumptionKwh": 2600,
      "capabilities": {
        "hasElectricVehicle": false,
        "hasSmartMeter": true,
        "hasHeatPump": true
      }
    },
    "agreements": {
      "termsAndConditions": true,
      "privacyPolicy": true,
      "revocationPolicy": true
    }
  }
}

If the customer has already cancelled their previous contract, transmit the cancellation date in previousSelfCancelledDate, e.g. "2026-10-31".

Example 2: B2B Move-In (bank transfer, previous supplier unknown)

{
  "tariffKey": "RabotSmart",
  "offerDate": "2026-09-29",
  "userAccount": {
    "emailAddress": "info@example-business.de",
    "password": null,
    "firstName": null,
    "lastName": null,
    "businessName": "Example GmbH",
    "dateOfBirth": "1975-01-01"
  },
  "contract": {
    "externalId": "ORDER-10002",
    "type": "Business",
    "industry": "ElectricalEquipment",
    "legalStructure": "GmbH",
    "deliveryAddress": {
      "firstName": null,
      "lastName": null,
      "businessName": "Example GmbH",
      "streetName": "Hauptstraße",
      "houseNumber": "100",
      "city": "München",
      "postCode": "80331",
      "countryCode": "DE"
    },
    "billingAddress": null,
    "bankDetails": null,
    "contractReason": "NewDeliveryLocation",
    "deliveryDetails": {
      "meterNumber": "987654321",
      "desiredTransitionDate": null,
      "moveInDate": "2026-11-15",
      "previousSelfCancelledDate": null,
      "previousSupplierCode": null,
      "bdewCode": null,
      "previousAnnualConsumptionKwh": 50000,
      "capabilities": {
        "hasElectricVehicle": false,
        "hasSmartMeter": true,
        "hasHeatPump": false
      }
    },
    "agreements": {
      "termsAndConditions": true,
      "privacyPolicy": true,
      "revocationPolicy": true
    }
  }
}

Common Validation Errors

Error Scenario	Cause	Solution
Missing mandatory field	A field marked 🛑 is `null` or omitted	Review the requirement tables above
Invalid contract reason combination	e.g. `moveInDate` provided with `ChangeOfSupplier`	Follow the contract reason decision tree
Missing bank details	`bankDetails` provided without `accountHolder` or `iban`	Provide both fields, or set `bankDetails` to `null` for bank transfer
B2C/B2B mismatch	e.g. `businessName` provided with `type: Private`	Align `contract.type` with the name, `industry` and `legalStructure` fields
BDEW code mismatch	`bdewCode` does not match the delivery postcode	Verify the grid operator’s BDEW code, or transmit `null`
Supply start delayed	A field marked ✅ was missing, so the data had to be collected from the customer	Transmit all change process fields with the initial order
Address cannot be matched	Address or meter number does not match grid operator data	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).

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 & Grid Operator Identifiers

4.2 Contract Reason

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

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

4.3 Consumption

4.4 Capabilities (`contract.deliveryDetails.capabilities`)

4.5 BDEW Code of the Grid Operator

5. Agreements (`contract.agreements`)

6. Response Messages

Quick Reference: Contract Reason Decision Tree

B2C vs B2B Decision Tree

Direct Debit vs Bank Transfer Decision Tree

Validation Summary

Example Payloads

Example 1: B2C Supplier Switch (RABOT cancels the previous contract)

Example 2: B2B Move-In (bank transfer, previous supplier unknown)

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 & Grid Operator Identifiers

​4.2 Contract Reason

​If contractReason = ChangeOfSupplier (Supplier Switch)

​If contractReason = NewDeliveryLocation (Move-In)

​4.3 Consumption

​4.4 Capabilities (contract.deliveryDetails.capabilities)

​4.5 BDEW Code of the Grid Operator

​5. Agreements (contract.agreements)

​6. Response Messages

​Quick Reference: Contract Reason Decision Tree

​B2C vs B2B Decision Tree

​Direct Debit vs Bank Transfer Decision Tree

​Validation Summary

​Example Payloads

​Example 1: B2C Supplier Switch (RABOT cancels the previous contract)

​Example 2: B2B Move-In (bank transfer, previous supplier unknown)

​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 & Grid Operator Identifiers

4.2 Contract Reason

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

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

4.3 Consumption

4.4 Capabilities (`contract.deliveryDetails.capabilities`)

4.5 BDEW Code of the Grid Operator

5. Agreements (`contract.agreements`)

6. Response Messages

Quick Reference: Contract Reason Decision Tree

B2C vs B2B Decision Tree

Direct Debit vs Bank Transfer Decision Tree

Validation Summary

Example Payloads

Example 1: B2C Supplier Switch (RABOT cancels the previous contract)

Example 2: B2B Move-In (bank transfer, previous supplier unknown)

Common Validation Errors

Questions or Concerns?