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.
After a new order has been received in the RABOT platform either by API or via the web order funnel, it goes through different stages, please see the different pathways visualised below:
Clearing the Change Process swiftly
The change process can take up to several weeks or more, which can impact the customer experience negatively as well as your own operations in all partnership types. As mentioned in our Build Your Own Funnel guide, there is certain information required for successful order creation; similarly, an order can swiftly clear the change process if all information in the POST /orders call body is provided when the order is submitted. See our guide to review mandatory, conditional and optional fields.
Orders submitted with the meter number proceed through the change process 80% faster than those submitted without.
Orders submitted with the MaLo Number proceed through the change process 90% faster than those submitted without.
Retrieving Order Status via the API
The order status is available for retrieval via the GET Orders endpoint. The response provides two layers of status information that work together to give a complete picture of where an order stands:
- Order-level fields (
order.state, order.processingInfo, order.denialReason): The overarching status of the order across its full lifecycle — present at all times.
- Change process fields (
order.deliveryState.*): Granular status information specific to the change process — only populated once an order has passed pre-validation and entered the change process.
Your system should digest the response data and present this within your native UI for the relevant teams to review and take action as needed. As a Whitelabel partner, this information is particularly important for your operations to analyse and prevent issues in the change process. As a Sales Affiliate partner, this information can help you streamline your pipeline and avoid incurring delays related to commission payments.
Understanding Order Status: Two Layers
Layer 1 — Order-Level Fields
These fields describe the overall lifecycle state of the order and are always present in the response:
| Field | Type | Description |
|---|
order.state | string | The current high-level state of the order. See Order States Table below. |
order.processingInfo | string | null | A message describing the outcome of RABOT’s internal pre-validation and transmission to the Market Communications Hub. Most relevant when diagnosing issues in the Open state. See order.processingInfo Reference below. |
order.denialReason | string | null | The reason an order was denied. Populated when order.state is Rejected. |
Layer 2 — Change Process Fields (order.deliveryState)
order.deliveryState is a nested object within the order response. It contains granular status information specific to the change process and is only populated once the order has passed pre-validation and entered the change process (i.e. order.state is Processing or beyond).
order.deliveryState is null while an order is in the Open state. It is populated once the order enters Processing and the change process begins.
| Field | Type | Description |
|---|
order.deliveryState.state | string | The change-process-specific state. Mirrors order.state but uses change process terminology. See state mapping below. |
order.deliveryState.startDate | date | The date the change process began. |
order.deliveryState.endDate | date | null | The date the change process concluded. null if the process is still ongoing. |
order.deliveryState.message | string | null | A detailed message from the market communication process, typically feedback from the grid operator. See deliveryState Message Reference below. |
order.deliveryState.denialReason | string | null | The reason for denial where applicable. Contains the same values as order.denialReason. |
order.deliveryState.cancellationReason | string | null | The reason for cancellation where applicable. |
Use order.state for high-level monitoring and workflow logic. Use order.deliveryState.state and order.deliveryState.message for detailed diagnostics — particularly when investigating stalled or rejected orders.
State Mapping: order.state vs order.deliveryState.state
order.state | order.deliveryState.state | Notes |
|---|
Open | (null) | Order is in pre-validation. order.deliveryState is not yet populated. |
Processing | InChangeProcess | The change process is active. Market communication with the grid operator is ongoing. |
PendingDelivery | DeliveryPending | The change process has completed successfully. A delivery start date has been confirmed. |
Delivery | Delivery | Energy supply is active. |
Rejected | Denied | The order was denied. See order.deliveryState.denialReason or order.denialReason. |
Revoked | Revoked | The customer revoked the order. |
Cancelled | Cancelled | The contract has been terminated. |
Order States Table
These are the possible values for order.state:
order.state | Description |
|---|
Open | The order has been received but has not yet entered the change process. This typically indicates that required data is missing or failed pre-validation (e.g. missing meter number, unconfirmed email address). Review order.processingInfo for details. |
Processing | The order has passed pre-validation and is now in the change process. Communication with market partners (grid operator, previous supplier) is ongoing. This can take a few days to several weeks depending on the actors involved. |
Rejected | The order has been denied, e.g. due to a failed credit check. See order.denialReason for the specific reason. |
Revoked | The customer has revoked the order. |
PendingDelivery | The change process has completed successfully. A contract confirmation and delivery start date have been sent to the customer. |
Delivery | The supply contract is active and RABOT is delivering energy to the delivery location. |
Cancelled | A contract termination has been received and an end of delivery date has been set. This can occur due to a customer-initiated termination or a new supplier communicating the termination via market communication processes. |
Unspecified | An unknown order state, indicating an error in communication with market partners. |
order.processingInfo Reference
order.processingInfo contains messages generated by RABOT’s internal pre-validation and transmission layer. These messages reflect the outcome of attempts to transfer the order to the Market Communications Hub and are most relevant when an order is in the Open state.
| Category | Description | What to check |
|---|
| Successfully transferred | The order was successfully transmitted to the Market Communications Hub. | No action required. |
| Missing identification data | No meter number, MaLo, or MeLo was provided. | Resubmit with a meter number or MaLo. |
| Invalid supplier or date data | Previous provider code is invalid or empty; transition date is missing. | Verify previousSupplierCode and all date fields. |
| Address data issues | Delivery address is incomplete or does not match records. | Verify all delivery address fields for completeness and accuracy. |
| Consumption data issues | Previous annual consumption value is invalid. | Ensure previousAnnualConsumptionKwh is ≥ 1000. |
| B2B data issues | Company name is missing for a commercial prosumer. | Ensure companyName is populated for all B2B orders. |
| Character or format errors | Meter number is too long or in an invalid format; character encoding issues (e.g. Special Characters). | Validate field formats and character encoding before submission. |
| Technical errors | Request timeout, internal service exception, or proxy error. | These are transient errors — retry the request. Contact Integration Management if the issue persists. |
| Other | Postcode is blacklisted; email address not yet confirmed; address data mismatch. | Review the specific message text and verify the relevant fields. |
deliveryState Message Reference
order.deliveryState.message contains detailed messages from the market communication process — typically feedback from the grid operator while the order is in the change process. These are most relevant when order.deliveryState.state is InChangeProcess and an order appears stalled or is progressing toward Rejected.
State: DeliveryPending / Delivery
| Message | Meaning |
|---|
Zustimmung | The grid operator has approved the supplier change. The change process completed successfully. |
State: InChangeProcess
These messages originate from the grid operator and are returned in German as part of the GPKE/GeLiGas market communication standard.
| Original (DE) | Translation (EN) | Likely cause and action |
|---|
| Die „Marktlokation-ID” oder „Tranchen ID” ist dem NB nicht bekannt. | The market location ID or tranche ID is unknown to the grid operator. | The MaLo ID is incorrect or unregistered. Verify the MaLo and resubmit. |
| Mit einem Identifikationskriterium war keine Marktlokation ermittelbar. | No market location could be identified using one identification criterion. | A single identifier (e.g. meter number only) was insufficient. Provide the MaLo in addition. |
| In der Kombination von zwei Identifikationskriterien war keine Marktlokation ermittelbar. | No market location could be identified using two identification criteria. | Two identifiers were provided but neither combination matched. Verify both meter number and MaLo. |
| In der Kombination von drei Identifikationskriterien war keine Marktlokation ermittelbar. | No market location could be identified using three identification criteria. | All provided identifiers failed to match. Contact the grid operator directly or raise with Integration Management. |
| Marktlokation nicht eindeutig bzw. nimmt nicht an der Marktkommunikation teil. | Market location is not unique or does not participate in market communication. | The location may be deregistered or matched to multiple entries. Manual investigation required. |
| Ermittelte Marktlokation liegt in einem in den letzten drei Jahren abgegebenen Netzgebiet. | The identified market location is in a grid area that changed operators within the last three years. | The grid operator on the order may be incorrect. Verify the currently responsible grid operator for this location. |
| Identifizierte Marktlokation ist stillgelegt. | The identified market location is decommissioned. | The delivery location is no longer active. The customer will need to contact their grid operator to reactivate it. |
| Die vom Anfragenden eingereichte Vollmacht wird als nicht wirksam betrachtet. | The power of attorney submitted by the requestor is not considered valid. | An authorisation documentation issue. Contact Integration Management. |
| Vorlauffrist wurde nicht eingehalten. | The required lead time was not observed. | The requested delivery start date did not allow sufficient lead time. A corrected order with an updated start date may need to be submitted. |
| Falscher Anwendungsfall, es ist bereits ein LF zugeordnet. | Incorrect use case — a supplier is already assigned to this location. | Verify the contract reason (ChangeOfSupplier vs. NewDeliveryLocation). |
| Marktlokation befindet sich zum Eingangsdatum der Meldung nicht mehr im Netzgebiet des NB. | The market location is no longer in the grid operator’s network area as of the submission date. | The grid territory may have changed. Verify the currently responsible grid operator. |
| Der LFA beendet die Belieferung und teilt sein Lieferendedatum in der Antwort mit. | The outgoing supplier is terminating supply and has communicated their end-of-supply date. | This is a normal response in a supplier change — the outgoing supplier has acknowledged the switch. No action required. |
| Ersatzversorgung wurde zum angefragten Termin beendet. | Emergency supply was terminated at the requested date. | Informational. The transition away from emergency supply has been processed. |
| Sonstiges, null. | Other / not specified. | No specific reason was provided by the grid operator. Contact Integration Management for investigation. |
The messages above represent the most frequently occurring values. Additional messages may appear as defined by the GPKE/GeLiGas market communication standards. If you encounter a message not listed here, contact Integration Management. State: Denied
When order.deliveryState.state is Denied, the reason is provided in order.deliveryState.denialReason. This field contains the same values as order.denialReason.
order.deliveryState.denialReason | Meaning |
|---|
InsufficientSolvency | The prosumer did not pass the insolvency or credit check. |
UnsuccessfulSupplierChange | The supplier change process could not be completed by the market partners. |
ContractCommitment | The prosumer is bound by an existing contract commitment and cannot switch suppliers at this time. |
Other | The order was rejected for a reason not covered by the above. Contact Integration Management for details. |
State: Revoked / Cancelled
order.deliveryState.state | order.deliveryState.message | Notes |
|---|
Revoked | null | The customer initiated the revocation. No further action required. |
Cancelled | null | See order.deliveryState.cancellationReason for termination details. |
Questions or Concerns?
Feel free to speak with our Integration Management Team or alternatively, ask our built-in AI assistant, Rabotini 🤖 (several languages supported).
