Zaptec Load Balancing and Service Bus FAQ

Use this FAQ to interpret Zaptec load-balancing and charger states when you build external control or monitoring integrations with the Zaptec API and Service Bus.

Use this FAQ when

• You set or restore installation-level AvailableCurrent for dynamic load balancing.
• You consume Service Bus state events for real-time charger states.
• You need to interpret current allocation, measured phase current, session end, charging mode, or phase switching behavior.
• You need to decide when an external load-balancing controller should act or stand down.

Key states and fields

1. Currents, Limits, and Key States

Q1.1: What is ChargeCurrentSet (state 708)? Is it the same as AvailableCurrent?

A: No, they are different:

• 708: ChargeCurrentSet is per‑charger allocated current, in amperes. It shows how much current the charger (within ZapCloud limits) is allowing the vehicle to draw on the configured phases.
• AvailableCurrent is an installation‑level budget: the total current that can be allocated across chargers on that installation/circuit.

ChargeCurrentSet is influenced by AvailableCurrent and other constraints, but is not equal to it.

Q1.2: What do the states 702 and 547 mean?

A:

• 702: ChargeMode

  • Represents the pilot/connection state, mainly relevant for Zaptec Go.
  • It does not represent a current limit.
  • Typical values you may observe:
    • 12: vehicle disconnected
    • 9: vehicle connected, not charging
    • 6: vehicle connected and charging
    • -12: wake‑up / error condition when the car does not respond

• 547: StandAloneCurrent

  • Used only when the charger is running in stand‑alone mode, i.e. not controlled by ZapCloud.
  • In normal cloud‑controlled operation, 547 does not limit charging current.

Q1.3: How do ChargeCurrentSet (708) and CurrentPhase1/2/3 (507/508/509) relate?

A:

• 708: ChargeCurrentSet is the allocated current for the charger.
• 507/508/509: CurrentPhase1/2/3 are the measured currents per phase.

The actual currents per phase can be lower than ChargeCurrentSet if the vehicle or cable is limiting, or if the effective per‑phase limit from installation constraints is lower.

Q1.4: Why can the actual current be lower than ChargeMaxCurrent (510)?

A: The effective per‑phase current is determined by the lowest active constraint among:

• The vehicle’s onboard charger limit (what the EV itself will accept).
• The cable rating (714: CableType).
• Installation‑level limits (e.g. AvailableCurrent, load balancing, phase switching).
• The charger’s own ChargeMaxCurrent (510).

It is therefore expected that measured current or ChargeCurrentSet may be below 510 and below AvailableCurrent, especially when the vehicle has a lower configured limit.

2. Installation Current and AvailableCurrent

Q2.1: Is AvailableCurrent always min(AvailableCurrentPhase1/2/3)?

A: No. While it may often look like the minimum of AvailableCurrentPhase1, AvailableCurrentPhase2, and AvailableCurrentPhase3, this is not a guaranteed invariant. You should not base logic on that equality always holding.

Q2.2: What is the recommended way for external load balancing to set current?

A: Recommended pattern:

1. Set a single AvailableCurrent at installation level by calling POST /api/installation/{id}/update.
2. Let Zaptec’s backend handle:
   • Phase distribution
   • Per‑charger allocation
   • Phase switching on Zaptec Pro and Zaptec Go 2

Only use AvailableCurrentPhase1/2/3 if you have a strong reason to enforce asymmetry between phases.

Q2.3: What takes priority: charger MaxCurrent vs installation MaxCurrent?

A: They apply at different levels:

• Installation/circuit maxCurrent (main fuse / circuit breaker) is the ceiling for AvailableCurrent; AvailableCurrent cannot effectively exceed this.
• Per charger, the effective ceiling is the minimum of:
  • Installation budget at that moment (AvailableCurrent, circuit limits)
  • Charger MaxCurrent
  • Cable rating
  • Vehicle’s own limit

Q2.4: If we lower AvailableCurrent below the installation maximum, does Zaptec ever restore it to max by itself?

A: No.

If you set AvailableCurrent below the installation maximum, it stays there until you change it.

The only “revert to max” behavior is when you call POST /api/installation/{id}/update and either:

• Omit AvailableCurrent (and/or per‑phase fields) from the payload, or
• Explicitly set them to null.

In that case the system falls back to the installation’s configured max current.

Q2.5: Is POST /api/installation/{id}/update the correct way to restore AvailableCurrent?

A: Yes. For external/dynamic load control:

• Reduce current:
  • Call POST /api/installation/{id}/update with a reduced AvailableCurrent.
• Restore:
  • Call the same endpoint and either clear AvailableCurrent (omit or set null) to revert to the max, or
  • Set a new explicit target value.

3. Detecting Session End

Q3.1: What is the authoritative way to detect that a charging session has ended?

A: Use real‑time state events from the Service Bus, not ChargeHistory polling, for session‑end logic.

Key fields:

• StateId 710: ChargerOperationMode

  • 3 = charging
  • 5 = connected, finished
  • 1 = no vehicle connected

• StateId 721: Session Identifier

  • Contains a session GUID when a session is active.
  • Changes or clears when a new session starts / old one ends.

A robust “session ended” condition is:

• 710 transitions from 3 (charging) to 5 (finished) or 1 (disconnected), and
• 721 changes or clears shortly after.

This is a good trigger point for actions such as “restore AvailableCurrent if safe.”

4. Phase Switching (3‑to‑1 and 1‑to‑3)

Q4.1: Can we identify charger model (Go, Go 2, Pro) via the public API?

A: Not via a direct “model” field. The public API does not expose a simple model = Go / Go 2 / Pro property.

For capabilities:

• Treat Zaptec Go as no dynamic phase switching.
• Treat Zaptec Pro and Zaptec Go 2 as phase‑switching capable, and base your logic on:
  • Installation configuration (threeToOnePhaseSwitchCurrent, single‑phase limits).
  • States like SetPhases (519).

ZapCloud internally knows the model and it can often be inferred from serial ranges, but this mapping is not exposed as a dedicated public property.

Q4.2: Can we identify if the connected vehicle supports 3‑to‑1 phase switching?

A: Not with a single explicit flag.

There is no API field saying “this vehicle supports mid‑session phase switching.” You can only:

• Enable phase switching in configuration, and
• Observe actual behaviour via:
  • 519: SetPhases
  • 708: ChargeCurrentSet
  • CurrentPhase1/2/3
  • Warnings (804)
  • Session events (723 CompletedSession)

If the EV repeatedly stops sessions or fails to draw current after switching, you can infer that it does not tolerate that switching pattern.

Q4.3: How do we detect that 3‑to‑1 dynamic phase switching is enabled on an installation?

A: Use:

• threeToOnePhaseSwitchCurrent (current config)
• defaultThreeToOneSwitchCurrent (default)

Typical interpretation:

• threeToOnePhaseSwitchCurrent = 0A → never switch down to 1‑phase (keep 3‑phase).
• threeToOnePhaseSwitchCurrent = 32A → effectively 1‑phase only.
• ~6–31A → 3→1 switching is enabled.

To treat dynamic 3→1 switching as “in play,” check:

1. threeToOnePhaseSwitchCurrent is in the active range (≈6–31 A), and
2. The charger model is one that supports it (Pro or Go 2).

Q4.4: Does Zaptec Go support 3‑to‑1 switching?

A: No.

Only Zaptec Pro and Zaptec Go 2 support dynamic 3↔1 phase switching.
Zaptec Go remains fixed to the configured phase rotation.

Q4.5: For Zaptec Go, does the charger always operate on the configured phase rotation?

A: Yes. There is no automatic 1‑phase/3‑phase switching during a session on Zaptec Go; it stays on the installation’s configured phase rotation.

Q4.6: How do we determine the current phase mode (1‑phase or 3‑phase)? Is state 519 correct?

A: Yes.

• Use State 519: SetPhases to determine the current phase mode; it is the canonical indicator for “1‑phase vs 3‑phase” in real time.
• There is no direct equivalent “current mode” property in GET /api/installation/{id} or GET /api/chargers/{id}.

For instantaneous snapshots, call GET /api/chargers/{id}/state; for continuous logic, consume 519 updates from the Service Bus.

Q4.7: Is there a difference in how 3‑to‑1 switching works between Zaptec Pro and Zaptec Go 2?

A: From an integration perspective, no significant difference:

• Both use the same concepts:
  • threeToOnePhaseSwitchCurrent
  • “Maximum allocated current when charging on single phase (A)”
  • “Switches allowed before locking to single phase”
  • “Allow return to three‑phase”
• Both react to changes in installation available current by switching between 3‑ and 1‑phase, according to configuration.

Hardware/firmware differ, but API/Service Bus semantics are essentially the same.

Q4.8: For single‑phase charging, can we identify the maximum configured current limit?

A: Yes.

• At installation level, the setting “Maximum allocated current when charging on single phase (A)” is the configured ceiling the backend will apply in 1‑phase mode.
• For a specific EV in 1‑phase, the effective ceiling is the minimum of:
  • That single‑phase limit
  • Installation/circuit fuse settings
  • Charger MaxCurrent
  • Cable rating
  • Vehicle’s own limit

5. Charging Modes and Load‑Balancing Compatibility

Q5.1: How do we detect which charging mode is active on an installation?

A: Use both:

• availableCurrentMode from the installation:

  • 0 = Default/Manual
  • 1 = Schedule
  • 2 = APM (Automatic Power Management)

• enabledFeatures bitmask for power‑management features, e.g.:

  • PowerManagement_EcoMode
  • PowerManagement_Schedule
  • PowerManagement_Apm

Typical mapping:

• Default / externally load‑balanced:

  • availableCurrentMode = 0
  • No Eco/APM/Schedule bits set.

• Eco Mode:

  • enabledFeatures includes PowerManagement_EcoMode.

• Schedule:

  • enabledFeatures includes PowerManagement_Schedule (often with availableCurrentMode = 1).

• APM:

  • enabledFeatures includes PowerManagement_Apm (with availableCurrentMode = 2).

Q5.2: When a non‑default mode is active, can an external system still perform load balancing via POST /api/installation/{id}/update?

A: In practice, treat this as not supported:

• The Dynamic Load Balancing guide requires the installation to be in Default mode for external LB.
• When Eco Mode, Schedule, or APM are active, internal power management is expected to be in control.
• External updates may be rejected or behave unexpectedly. You may see business errors like 527 when Eco Mode blocks an update.

Recommended pattern:

• Always pre‑check availableCurrentMode and enabledFeatures.
• Implement logic such as “external LB only allowed when Default mode is active and Eco/APM/Schedule are off.”
• If POST /installation/{id}/update returns a 5xx business error (e.g. 527), surface it as “backend rejected control in current mode.”

6. Phase Switching: Session Interruptions and Warnings

Q6.1: In “EV connected, waiting for available power”, will POST /api/installation/{id}/update still work?

A: Yes.

In that state:

• ChargerOperationMode (710) is typically 2 (“vehicle connected; requesting to charge”), but not actually drawing current yet.

POST /api/installation/{id}/update will still adjust installation limits. If you raise AvailableCurrent (and other limits allow), the charger can transition back to mode 3 (charging) and resume.

Q6.2: How can we detect when PropertySessionMaxStopCount / WARNING_MAX_SESSION_RESTART has terminated a session?

A: This is controlled by the configuration slider “Switches allowed before locking to single phase.”

When the limit is reached and the session is terminated:

• It is observable via Service Bus:
  • 804: Warnings for that charger.
  • 723: CompletedSession event (includes start/stop and reason details).

It is not surfaced as a dedicated error code on POST /api/installation/{id}/update; that call typically still succeeds since it is only changing limits.

Q6.3: What is the “charging circuit breaker” mentioned in the note about disabling 1‑to‑3 phase switching?

A: In this context, it is the protective device / fuse configured for the EV charging circuit in the installation (e.g. the breaker you see under Installation Circuits / Main Fuse).

You do not need to disable 1‑to‑3 switching just because a breaker exists. The intent of the note is:

• If that breaker actually trips in real life while phase switching is used, you should tune or disable phase switching for that installation to avoid repeated trips.

Q6.4: Can the “Charging system circuit breaker (A)” be configured higher than the main “Circuit breaker (A)”? What is the effective ceiling?

A: Configuration may allow that, but at runtime the effective ceiling is always the lowest relevant limit, such as:

• Main breaker
• Charging system breaker / APM bracket
• Installation maxCurrent
• Single‑phase max
• Other configured limits

If the charging‑system breaker is configured higher than the main breaker, the main breaker still wins as the effective cap.

Q6.5: How do we see that a vehicle could not successfully switch from 1‑phase to 3‑phase?

A: There is no single “failed to switch” flag. You must infer it from:

• 519: SetPhases (what backend requested),
• 708: ChargeCurrentSet (allocated current),
• CurrentPhase1/2/3 (what is actually drawn), and
• 804: Warnings plus 723: CompletedSession for abnormal termination.

A typical pattern:

• Backend sets SetPhases to 3‑phase,
• But the EV continues drawing as if on 1‑phase (or soon terminates the session).

That pattern suggests the vehicle does not support or tolerate the attempted phase change.

7. Charger and Installation State Interpretation

Q7.1: What pre‑checks are recommended before calling POST /api/installation/{id}/update for load balancing?

A: For a robust controller:

1. Mode checks

   • Installation is in Default mode (no Eco/APM/Schedule).
   • Otherwise, treat it as “not externally controllable.”

2. Connectivity

   • Relevant chargers are online (IsOnline = 1).

3. Context

   • Inspect ChargerOperationMode (710) to understand whether your change will impact an active session, a pending one, or only future sessions.

The endpoint can be safely called at any time and you can rely on HTTP errors as well, but these pre‑checks help you handle blocked or ineffective commands more gracefully.

Q7.2: How does ChargerOperationMode (710) affect the impact of POST /installation/{id}/update? Are commands queued?

You will typically see these values:

• 0: Unknown
• 1: Disconnected
• 2: Connected_Requesting
• 3: Connected_Charging
• 5: Connected_Finished

Impact on load balancing:

• Mode 3 (Connected_Charging)

  • This is the only state where a change to AvailableCurrent has an immediate effect on an active session.

• Mode 2 (Connected_Requesting)

  • There is no per‑charger command queue.
  • You are still changing installation‑level limits. When the session eventually moves to mode 3, it will start under whatever limits are in place at that time.

• Mode 5 (Connected_Finished)

  • Session is over; a change will not affect that session but will apply to future ones.

In other words, your commands are not queued per charger; they continuously update the installation budget, whose effect depends on current charger states.