Skip to main content
This API is alpha. It can change without notice. Today it covers the German market.
A supplier switch lets you take over supply of an accounting point as the new supplier. You tell Engrate which accounting point you want to supply and from which date. Engrate sends the request to the grid operator in the format of the market. Then Engrate keeps the decision of the grid operator as the state of the switch.

Declare a switch

You declare supplier switches in a structure batch: Submit Structure Batch. A batch holds 1 to 100 structuring actions. Each action creates one supplier switch. For each switch, you give:
  • The accounting point, by the identifier that the market gives it.
  • The effective date: the date from which you want to supply the accounting point.
  • The balance group that you supply the accounting point in.
  • The grid operator that the accounting point connects to.
  • The customer at the accounting point.
Some markets need more data. See Supplier switches in Germany. Engrate applies all the actions of a batch or none of them. Engrate refuses the whole batch with a conflict when:
  • An action names an accounting point that already has an open switch. A switch is open while it is pending, requested or accepted.
  • Two actions of the batch name the same accounting point.
The conflict tells you which actions caused it. Remove or change these actions, then submit the batch again. A conflict is not a decision of the market: Engrate sends nothing to the market for a refused batch. When Engrate applies a batch, it adds each accounting point to your organization if it is not there yet. The result gives the identifier of each new switch.

Follow a switch

Read the state of your switches with List Supplier Switches. You can filter by accounting point, state and effective date. Engrate reads the state as of today on the calendar of the market. No market message marks the effective date, so an accepted switch becomes effected on that date without a new message.

Switch requests

Each switch shows the switch requests that Engrate made for it, oldest first. A switch request is one submission of the switch to the market. It ends in one of three ways:
  • Accepted: the grid operator accepted the switch.
  • Rejected: the grid operator rejected the switch. The rejection gives the reason of the market in the words of the market.
  • Failed: the request ended without a decision. For example, the message did not get to the market or Engrate cannot confirm that it did, the market could not process the message, or the market sent no decision in 10 days.
When a request fails and the market has not decided on the switch, the switch goes back to pending with a block. Engrate does not send a failed request again on its own. A decision on an earlier request still applies after a later request fails. Each request also shows its market message: where the message is on its way to the market, and the references that the market quotes in its answers. Use these references when you talk to the grid operator about a request.

After the switch

When the grid operator accepts the switch, you supply the accounting point from the effective date. The accounting point shows this supply period together with its master data. See Accounting points.

Supplier switches in Germany

In Germany, the accounting point is a market location (Marktlokation). Its identifier is the 11-digit MaLo-ID. The grid operator is the Netzbetreiber that the market location connects to.

What you declare

For enfg_eligibility, give one of:
  • customer_qualifies, with the privilege reasons. Get the codes from List EnFG Privilege Reasons. The customer must also tell the grid operator, as § 52 EnFG requires.
  • customer_does_not_qualify.
  • location_does_not_qualify, when the market location cannot get reduced levies.

The switch request

Engrate sends the switch request to the grid operator as an EDIFACT UTILMD message: the supply-start request (Anmeldung). The grid operator answers with a UTILMD message that accepts or rejects the request. When the grid operator cannot read or process the message, it answers with a CONTRL or APERAK message. Engrate shows this as a failed request.

The effective date

The effective date is the first day of supply. The request must reach the grid operator no later than the day before the last working day before the effective date. The grid operator decides if the request came in time.

The market decision

The grid operator decides on each request. When it rejects a request, market_reason.code is the answer code of the German market, and market_reason.text is the text that the grid operator sent with it. The text is usually in German.

Example

A structure batch with one supplier switch for a German market location that consumes energy: