Create new order

You can use this endpoint to create a new order. See the guide section Build your own Funnel for additional information.

Required input

The following information is mandatory to create an order:

General information

a valid tariffKey (see list tariffs)
customer information in useraccount:
- firstName and lastName for private customers, businessName for business customers.
- a validated email address of the customer
the deliveryAddress object with
- firstName and lastName for private customers, businessName for business customers.
- complete postal address of the delivery location
bankDetails need to be complete with accountHolder, iban, bic and bankName for SEPA. Set bankDetails: null for payment by invoice
deliveryDetails has to filled with
- maLoIdentifier or meterNumber of the delivery point
- the BDEW code of the previous supplier in previousSupplierCode

Use case: new delivery location

If the customer just moved into the location, i.e. has no previous supply contract for the delivery location:

contractReason has to be set to NewDeliveryLocation
deliveryDetails has to filled with
- moveInDate set to the date the customer will move into the new location. This will be used as desired start date for the contract
- previousAnnualConsumption has to be filled and set to the expected annual energy consumption.

Use case: change of supplier

If the customer already has a supply contract in the delivery location:

contractReason has to be set to ChangeOfSupplier
The name in deliveryAddress has to match with the contract holder of the previous supply contract
deliveryDetails has to filled with
- previousAnnualConsumption has to be filled and set to the annual energy consumption as reported by the previous supplier
- If the customer has already cancelled the contract with the previous supplier
  - previousSelfCancelledDate has to be filled. This will be used as desired start date for the new contract
- If the customer wants Rabot to take care of cancelling the contract with the previous supplier:
  - desiredTransitionDatehas to be filled

Requires create:orders scope.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request data object

Information about a new order to be created

tariffKey

string

Tariff key of the tariff to be used

Example:

"RabotSmart"

offerDate

string<date> | null

Date, for which the offer was given. Uses today as default, if not provided.

Example:

"2025-08-22"

userAccount

object

Information about user account, that should be created and bound with the tariff. If an account for the same user (identified by the email address) already exists, the contract is linked to the existing user account instead.

Hide child attributes

userAccount.emailAddress

string

E-mail address of the account. This is used for email communication (e.g. when sending the order confirmation), and also serves as the login name for the mobile app.

Example:

"[email protected]"

userAccount.phoneNumber

string | null

Phone number of the account holder

Example:

"+491234567890"

userAccount.password

string | null

Password in plain text. If no password is provided, a random password is generated, and the user will have to use the forget password flow to define a new password.

Example:

"SomeExamplePassword987."

userAccount.firstName

string | null

First name of the account holder

Example:

"Max"

userAccount.lastName

string | null

Last name of the account holder

Example:

"Mustermann"

userAccount.businessName

string | null

Company name if this is a business account

userAccount.gender

enum<string>

Gender of the account holder

Available options:

Male,

Female,

Other

userAccount.dateOfBirth

string<date> | null

Date of birth of the account holder

contract

object

Information about the contract, that should be created for this order

Hide child attributes

contract.externalId

string | null

External identifier of contract created from an external system.

Example:

"urn:acme:contract:ffa98ecb-f28c-442d-b52e-7ffdc97ba676"

contract.type

enum<string>

Type of the contract.

Available options:

Private,

Business

Example:

"Personal"

contract.deliveryAddress

object

Delivery address of the contract.

Hide child attributes

contract.deliveryAddress.title

string | null

Academic title or NULL if none

Example:

"Dr."

contract.deliveryAddress.firstName

string | null

First name or NULL if business address

Example:

"Thomas"

contract.deliveryAddress.lastName

string | null

Last name or NULL if business address

Example:

"Mustermann"

contract.deliveryAddress.businessName

string | null

Business name in case of business address or NULL if person

Example:

null

contract.deliveryAddress.gender

enum<string>

Gender of the address holder

Available options:

Male,

Female,

Other

contract.deliveryAddress.extension

string | null

Address extension

Example:

null

contract.deliveryAddress.streetName

string

Street name

Example:

"Grüner Weg"

contract.deliveryAddress.houseNumber

string

House number or NULL if none

Example:

"42"

contract.deliveryAddress.city

string

Name of the city

Example:

"Berlin"

contract.deliveryAddress.postCode

string

Postcode in valid format

Example:

"14109"

contract.deliveryAddress.countryCode

string

ISO 3166 A2 code of the country

Example:

"DE"

contract.billingAddress

object

Billing address of the contract.

Hide child attributes

contract.billingAddress.title

string | null

Academic title or NULL if none

Example:

"Dr."

contract.billingAddress.firstName

string | null

First name or NULL if business address

Example:

"Thomas"

contract.billingAddress.lastName

string | null

Last name or NULL if business address

Example:

"Mustermann"

contract.billingAddress.businessName

string | null

Business name in case of business address or NULL if person

Example:

null

contract.billingAddress.gender

enum<string>

Gender of the address holder

Available options:

Male,

Female,

Other

contract.billingAddress.extension

string | null

Address extension

Example:

null

contract.billingAddress.streetName

string

Street name

Example:

"Grüner Weg"

contract.billingAddress.houseNumber

string

House number or NULL if none

Example:

"42"

contract.billingAddress.city

string

Name of the city

Example:

"Berlin"

contract.billingAddress.postCode

string

Postcode in valid format

Example:

"14109"

contract.billingAddress.countryCode

string

ISO 3166 A2 code of the country

Example:

"DE"

Example:

null

contract.bankDetails

object

Bank details of the contract or NULL, when invoice pays due.

Hide child attributes

contract.bankDetails.accountHolder

string | null

Name of the account holder. When used to create an order, if the value is not provided, the name of the customer from billing address (or delivery address, when billing address is not provided) will be used.

Example:

"Thomas Heinrich Mustermann"

contract.bankDetails.iban

string

IBAN of the account.

Example:

"DE89370400440532013000"

contract.bankDetails.bic

string | null

BIC of the account.

Example:

"DEUTDEFF"

contract.bankDetails.bankName

string | null

Name of the bank.

Example:

"Deutsche Bank"

contract.bankDetails.hasAcceptedDirectDebit

boolean

Flags, if the direct debit has been accepted.

Example:

true

contract.contractReason

enum<string>

Reason, why the contract was created.

Available options:

NewDeliveryLocation,

ChangeOfSupplier

Example:

"NewDeliveryLocation"

contract.deliveryDetails

object

Information about the point of delivery.

Hide child attributes

contract.deliveryDetails.previousAnnualConsumptionKwh

integer<int32>

required

Previous annual consumption in kWh.

Example:

2600

contract.deliveryDetails.meterNumber

string | null

Identification number of the metering device bound to the contract.

Example:

"123456789"

contract.deliveryDetails.maLoIdentifier

string | null

Market location identifier; will be used when provided, otherwise it will be retrieved from MaKo service.

Example:

"99987999749"

contract.deliveryDetails.meLoIdentifier

string | null

Metering location identifier; will be used when provided, otherwise it will be retrieved from MaKo service.

Example:

"DE99911149565001246597500M01ID018"

contract.deliveryDetails.desiredTransitionDate

string<date> | null

Date of the desired transition to a new supplier.

Example:

"2024-05-01"

contract.deliveryDetails.moveInDate

string<date> | null

Date when the customer moves in to a location of delivery point, if applicable.

Example:

null

contract.deliveryDetails.previousSelfCancelledDate

string<date> | null

Date of previous contract self-cancellation, if applicable.

Example:

"2024-04-22"

contract.deliveryDetails.previousSupplierCode

string | null

BDEW code of previous supplier, or NULL if none.

Example:

"9979250000006"

contract.deliveryDetails.capabilities

object

Capabilities of the delivery point.

Hide child attributes

contract.deliveryDetails.capabilities.hasElectricVehicle

boolean

Flag, indicating if the contract holder has an electric vehicle.

Example:

false

contract.deliveryDetails.capabilities.hasSmartMeter

boolean

Flag, indicating if the contract holder has a smart meter.

Example:

true

contract.deliveryDetails.capabilities.hasHeatPump

boolean

Flag, indicating if the contract holder has a heat pump.

Example:

true

contract.agreements

object

Contract agreements.

Hide child attributes

contract.agreements.termsAndConditions

boolean

Flags, whether the terms and conditions have been accepted.

Example:

true

contract.agreements.privacyPolicy

boolean

Flags, whether the privacy policy has been accepted.

Example:

true

contract.agreements.revocationPolicy

boolean

Flags, whether the revocation policy has been accepted.

Example:

true

contract.transactionDateTime

string<date-time> | null

Date and time of the transaction that created this contract. If not provided, current date and time is used.

Example:

"2024-04-01 00:00:00"

campaignCode

string | null

Optional campaign code, if campaign is to be used

Response

200 - application/json

customerNumber

string

Customer number of created customer

Example:

"234567890"

contractNumber

string

Number of newly created contract

Example:

"345678901"

Introduction

Get Started

Quickstart

Guides

Updates

API reference

Required input

Authorizations

Body

Response

Introduction

Get Started

Quickstart

Guides

Updates

API reference

​Required input

Authorizations

Body

Response

Required input