# Zaptec Documentation

> Documentation for Zaptec

Append .md to any documentation page URL to get its markdown version.

## Guides
- [Zaptec Developer Guides](https://docs.zaptec.com/docs/overview.md): Choose the right Zaptec integration method and learn how to build with Zaptec APIs, Service Bus events, and OCPP capabilities.
- [Getting started](https://docs.zaptec.com/docs/getting-started.md): This guide will assist you in swiftly setting up and using the Zaptec integration capabilities.
- [Authentication](https://docs.zaptec.com/docs/api-authentication.md): Authenticate with the ZapCloud API and Zaptec integrations API  by requesting an OAuth bearer token and sending it in the Authorization header for protected API requests.
- [API Usage Guidelines](https://docs.zaptec.com/docs/api-usage-guidelines.md): Guidelines for using the Zaptec API responsibly, including authentication, request handling, rate limits, Service Bus updates, permissions, and dynamic load balancing.
- [API Fair Use Policy](https://docs.zaptec.com/docs/api-fair-use-policy.md): Defines acceptable use of the Zaptec API, including rate limits, Service Bus recommendations, data handling, security requirements, prohibited activities, and enforcement.
- [API Rate Limiting](https://docs.zaptec.com/docs/api-rate-limiting.md): This document outlines the rate limiting Zaptec API is using for the public audience and explains how to design the integration in a good way.
- [Identify device types](https://docs.zaptec.com/docs/identify-device-types.md)
- [Third-party integration onboarding flow](https://docs.zaptec.com/docs/step-by-step-flow-granting-third-party-access-to-user-installations-via-lookup-key.md): Explains how third-party integrators can request user consent, use a lookup key, handle redirects, and link installations or chargers through the Zaptec access request flow.
- [Roles and permissions](https://docs.zaptec.com/docs/roles-and-permissions.md)
- [Common integration use cases](https://docs.zaptec.com/docs/common-integration-use-cases.md)
- [Solar Integration with Zaptec Go and Zaptec Go 2](https://docs.zaptec.com/docs/solar-integration-and-zaptec.md): Integrate solar charging with Zaptec Go and Zaptec Go 2 using either Zaptec dynamic load balancing or OCPP 1.6J Smart Charging profiles.
- [Dynamic load balancing](https://docs.zaptec.com/docs/dynamic-load-balancing-with-the-zaptec-api.md): Track charger state with Service Bus events and adjust installation-level AvailableCurrent through the Zaptec API for dynamic load balancing.
- [3- to 1-phase switching with Zaptec Go 2](https://docs.zaptec.com/docs/3-to-1-phase-switching-with-zaptec-go-2.md)
- [When and how to use pause and resume command](https://docs.zaptec.com/docs/understanding-finalstopactive-and-resume-command-behavior.md)
- [Two approaches to pause and resume charging during a session](https://docs.zaptec.com/docs/approaches-to-start-and-stop-charging-during-a-session.md): This guide describes two approved methods for pausing and resuming a charging session: adjustments to MaxCurrent and explicit pause/resume commands. Use only one method per session. The commands approach is preferred for clarity and for chargers that may be offline.
- [Web hooks Authentication type](https://docs.zaptec.com/docs/webhook-authentication.md): Webhooks enable seamless integration between Zaptec charging stations and external authorization or payment providers. When a user initiates a charging session, Zaptec sends an HTTP POST request to the configured external provider. The provider then decides whether to authorize the session. If approved, charging proceeds; otherwise, it is denied. This approach allows for flexible authentication and payment processing, ensuring secure and efficient charging management.
- [Web hook authorization](https://docs.zaptec.com/docs/web-hook-authorization.md): Authorize charging sessions with your backend and receive completed session data for logging and billing through ZapCloud web hooks.
- [Zaptec Service bus subscriptions](https://docs.zaptec.com/docs/zaptec-service-bus-subscriptions.md): Learn how to configure Zaptec Service Bus subscriptions to receive real-time AMQP charger state updates, retrieve credentials, and understand message format and limits.
- [State Observation Reference](https://docs.zaptec.com/docs/state-observation-reference.md): State observations provide detailed information about the operational status, performance, and measurements of Zaptec chargers. This document serves as a reference guide to commonly available state observations.
- [Zaptec Load Balancing and Service Bus FAQ](https://docs.zaptec.com/docs/zaptec-load-balancing-telemetry-developer-faq.md): Answers common integration questions about Zaptec load balancing, charger state, available current, session-end detection, charging modes, and dynamic phase switching.
- [OCPP within Zaptec](https://docs.zaptec.com/docs/ocpp-within-zaptec.md)
- [OCPP1.6J Cloud](https://docs.zaptec.com/docs/ocpp16j-cloud.md): Cloud based OCPP
- [OCPP1.6J Cloud configuration](https://docs.zaptec.com/docs/configuring-your-installation-to-an-ocpp-server.md)
- [Supported OCPP1.6J cloud commands](https://docs.zaptec.com/docs/supported-ocpp16j-cloud-commands.md)
- [Legacy OCPP Behavior](https://docs.zaptec.com/docs/legacy-ocpp-behavior.md): This page explains how Zaptec chargers determine the identity used for basic authentication in OCPP-J 1.6 connections. It covers the difference between legacy and standard behavior, how URLs are resolved at the charger and installation level, and how to configure the correct authentication mode in the Zaptec Portal.
- [Reserve Now Feature](https://docs.zaptec.com/docs/reserve-now-feature.md)
- [OCPP TriggerMessage Command](https://docs.zaptec.com/docs/ocpp-triggermessage-command.md): The OCPP TriggerMessage command enables external systems to actively request specific messages from a charging station. This provides powerful tools for diagnostics, operational oversight, and data analysis.
- [OCPP 1.6J](https://docs.zaptec.com/docs/ocpp16j.md): OCPP1.6J also referred to as 'box level' OCPP 1.6J, is available on Zaptec Go and Go2 and Zaptec Pro with supported firmware
- [OCPP 1.6J configuration](https://docs.zaptec.com/docs/zaptec-go-ocpp16j-configuration-guide.md): OCPP1.6J, also known as 'box-level' OCPP 1.6J, is available on Zaptec Go,Zaptec Go2 and Zaptec Pro with supported firmware. This guide walks you through setting up and managing OCPP 1.6J functionalities on your Zaptec chargers.
- [Zaptec Go OCPP 1.6J Non-standard implementation guide](https://docs.zaptec.com/docs/ocpp16j-non-standard-implementation-guidelines-on-zaptec-go.md): The Zaptec Go OCPP1.6J Non-standard implementation guide provides detailed information on the Zaptec Go's OCPP implementation. Specifically, it highlights the characteristics, variations, and extensions that are unique to this implementation compared to the standard OCPP protocol. This guide is intended for integrators, developers, and operators to facilitate a clear understanding and successful interaction with Zaptec Go charging stations.
- [PowerActiveImportDeltaForEagerMeterValueSample](https://docs.zaptec.com/docs/poweractiveimportdeltaforeagermetervaluesample.md)
- [Zaptec OCPP 1.6J Compliance FAQ](https://docs.zaptec.com/docs/zaptec-ocpp16j-compliance-faq.md)
- [Zaptec Go and Go2 OCPP 1.6J supported configuration keys](https://docs.zaptec.com/docs/zaptec-go2-ocpp-16j-supported-configuration-keys.md): The list below displays all supported configuration keys, their corresponding values, and indicates whether each key is Read Only and/or Mandatory for the Go and Go2.
- [OCPP Common Smart Charging Use Cases](https://docs.zaptec.com/docs/ocpp-common-smart-charging-use-cases.md): This document describes common Smart Charging use cases using OCPP 1.6J, with a focus on pausing and resuming an active charging session using TxProfiles.  The examples below assume that Smart Charging is supported by the charge point and that TxProfile is used for transaction-specific control.
- [OCPP 1.6J for Zaptec Pro](https://docs.zaptec.com/docs/ocpp-16j-for-zaptec-pro.md): Request OCPP 1.6J firmware for Zaptec Pro, review supported messages and release notes, configure installations, and provide feedback.
- [Zaptec Pro OCPP 1.6J supported configuration keys](https://docs.zaptec.com/docs/zaptec-pro-ocpp16j-supported-configuration-keys.md): The list below displays all supported configuration keys, their corresponding values, and indicates whether each key is Read Only and/or Mandatory for the Zaptec Pro for firmware version 7.5.4.0+
- [Authorizing charge requests](https://docs.zaptec.com/docs/integration-guide.md)

## API Reference
- [Completed sessions (deprecated)](https://docs.zaptec.com/reference/api_chargehistory_get.md): **Deprecated**: Use `GET /api/sessions/archived` instead.   This endpoint is being phased out with the following timeline:   - From **2026-08-01**, closed sessions older than two years are no longer returned.   - From **2027-01-01**, closed sessions are removed / endpoint sunset.   Retrieves all completed charge sessions accessible by the current user, matching the provided filters.   Default page size: 50. Max: 100.
- [Usage report](https://docs.zaptec.com/reference/api_chargehistory_installationreport_post.md): Retrieves a usage report based on the provided filters (requires installation owner permissions).
- [Chargers](https://docs.zaptec.com/reference/api_chargers_get.md): Retrieves all chargers accessible by the current user, matching the provided filters.   By default, returns the first 50 items. Use `pageIndex` for pagination or adjust `pageSize` (max: 100).
- [Charger details](https://docs.zaptec.com/reference/api_chargers_id_get.md): Retrieves the specified charger (requires owner or service permissions).
- [Update charger](https://docs.zaptec.com/reference/api_chargers_id_update_post.md): Updates charger properties (requires owner or service permissions).     <b>Charge Current Settings:</b>  The `maxChargeCurrent` and `minChargeCurrent` properties should generally not be used. These are intended for special cases where an external party must override the Zaptec load balancer, which may cause unexpected behavior.   It is recommended to control the charging system using the installation’s `AvailableCurrent` setting instead.  <b>Offline Current/Phase Override:</b>  Use only when charging stations must not automatically optimize offline current or phases.   - Set `OfflineChargeCurrent` to `-1` to enable automatic allocation.  - Any value between `0` and `32` overrides the automatic setting. `null` is ignored.  - Set `OfflineChargePhase` to `0 (Phases.None)` to enable automatic allocation.  - Any other valid value will override the automatic setting.   Ensure that the total of all overridden values in an installation does not exceed the fuse limit.  <b>Meter Value Interval:</b>  Controls how often periodic energy data is reported.   The recommended default is `30 minutes`. Setting this to `0` disables periodic reporting, affecting both session data and signed meter values.
- [Charger state](https://docs.zaptec.com/reference/api_chargers_id_state_get.md): Retrieves the current state properties (observations) for the specified charger   (requires owner or service permissions).   State IDs may vary by charger model.   Current-generation ZapCharger Smart supports <b>Observations</b> from   <a href="/api/constants" target="_blank">api/constants</a>
- [Send charger command](https://docs.zaptec.com/reference/api_chargers_id_sendcommand_commandid_post.md): <b>Permissions:</b> Requires owner or service-level access.  <b>Supported Command IDs:</b>              - <b>102</b> – Restart the charger              - <b>200</b> – Upgrade charger firmware              - <b>506</b> – Stop or pause charging              - <b>507</b> – Resume charging              - <b>10001</b> – Deauthorize and stop charging  <b>Command 10001 – Deauthorize and Stop:</b>              The caller must ensure that no new charging sessions are authorized until the command is completed.  <b>Command 506 – Pause/Stop Charging:</b>                  - Requires firmware version > 3.2 on PRO chargers                  - Typical usage: For chargers in active charging mode (state <b>ChargeOperationMode, 710</b> = 3). Other edge cases are supported,             but this is the most common scenario.                  - The command will be rejected if the charger is already paused (state <b>ChargeOperationMode, 710</b> = 5 and <b>FinalStopActive, 718</b> = 1)                 or disconnected (state <b>ChargeOperationMode, 710</b> = 1) <b>Commands 507 – Resume Charging:</b>                  - Requires firmware version > 3.2 on PRO chargers                  - Typical usage: For chargers in paused state (state <b>ChargeOperationMode, 710</b> = 5 and <b>FinalStopActive, 718</b> = 1).             Other edge cases are supported, but this is the most common scenario.              - The command will be rejected if the charger is not in paused mode (state <b>ChargeOperationMode, 710</b> = 5 and <b>FinalStopActive, 718</b> = 1)                  neither Scheduler is active (state <b>NextScheduleEvent, 763</b> is set)
- [Firmware details](https://docs.zaptec.com/reference/api_chargerfirmware_installation_installationid_get.md): Retrieves firmware details for all chargers in the specified installation   (requires owner or service permissions).
- [Static Constants](https://docs.zaptec.com/reference/api_constants_get.md): Retrieves a set of predefined constants that rarely change but may be updated occasionally.   These constants include schemas, enumerations, supported languages, country data,   charger operation modes, network types, user roles, error codes, settings, and more.   This data provides system-wide reference values, reducing the need for frequent queries.
- [Installations](https://docs.zaptec.com/reference/api_installation_get.md): Retrieves all installations accessible by the current user, matching the provided filters.   By default, returns the first 50 items. Use <b>pageIndex</b> for pagination or adjust <b>pageSize</b> (max: 100).
- [Installation details](https://docs.zaptec.com/reference/api_installation_id_get.md): Retrieves details for the specified installation.   The level of detail available depends on the current user's permissions.
- [Messaging connection (deprecated)](https://docs.zaptec.com/reference/api_installation_id_messagingconnectiondetails_get.md): Retrieves connection details for subscribing to live AMQP 1.0 charger events   for the specified installation (requires owner or service permissions).  <b>WARNING:</b> This feature is <b>deprecated</b>.   Use a single <b>User Group</b> subscription to receive updates for all installations instead.
- [Update installation](https://docs.zaptec.com/reference/api_installation_id_update_post.md): Updates installation properties (requires owner or service permissions).  <b>Available Current:</b> Provide <b>either</b><i>AvailableCurrent</i>   or (<i>AvailableCurrentPhase1, AvailableCurrentPhase2, AvailableCurrentPhase3</i>).   Updating available current will instantly trigger phase and load balancing for the installation.   Vehicles will adjust their charging settings within <b>5 seconds</b>.     <b>Usage Recommendations:</b>  - Do not update this setting more than once every <b>15 minutes</b> to prevent charging interruptions.  - Available current is limited to the installation’s configured maximum current (circuit breaker current).  - If set to <b>null</b> (not provided), the installation will revert to its maximum current setting.
- [Installation hierarchy](https://docs.zaptec.com/reference/api_installation_id_hierarchy_get.md): Retrieves an installation along with its circuit and charger hierarchy   (requires owner or service permissions).  <b>Note:</b> Only basic properties of the returned model will be populated.
- [Session details](https://docs.zaptec.com/reference/api_session_id_get.md): Retrieves details for the specified charging session.
- [Set session priority](https://docs.zaptec.com/reference/api_session_id_priority_post.md): Assigns priority to a charging session (requires owner or service permissions).   Prioritized sessions are allocated before unprioritized ones and will receive at least the prioritized current.  <b>Important considerations:</b>  - Multiple sessions can be prioritized; the caller must ensure enough available current.  - If there is insufficient current, prioritized sessions are allocated on a first-come, first-served basis.  - After allocating prioritized sessions, any remaining current is distributed among unprioritized sessions.
- [Archived sessions](https://docs.zaptec.com/reference/api_sessions_archived_get.md): Retrieves completed charge sessions accessible by the current user, filtered by date range and exactly one of: an installation, a single charger, or an authorized user (the calling user's own id; support may pass any user's id). Results are returned in cursor-paginated pages in the requested `order` (oldest first by default); when `hasMore` is true, send the returned `cursor` as `?cursor=` on the next request to fetch the next page. Default page size: 50. Max: 200.
- [Messaging connection](https://docs.zaptec.com/reference/api_usergroups_id_messagingconnectiondetails_get.md): Retrieves connection details for subscribing to live AMQP 1.0 charger events   for installations within the specified user group (requires owner or service permissions).   For more details on working with AMQP and Service Bus, refer to the   <a href="https://learn.microsoft.com/en-us/azure/service-bus-messaging/" target="_blank"> Microsoft Azure Service Bus documentation</a>.
- [Set OCPP Password (plain text) for a charger](https://docs.zaptec.com/reference/post_chargers-chargerid-ocpp-settings-password.md): Expects `password` as plain text in the request payload.  This endpoint encodes the plain-text password to hex before forwarding it to the charger.  If you already have an encoded OCPP AuthorizationKey that must be used as-is, use `/chargers/{chargerId}/ocpp/settings/encodedauthorizationkey` instead.
- [Set encoded OCPP Password (AuthorizationKey) for a charger](https://docs.zaptec.com/reference/post_chargers-chargerid-ocpp-settings-encodedauthorizationkey.md): Sets the charger's OCPP AuthorizationKey from `encodedPassword` and configures the charger to use that encoded key as-is (without decoding).  Expected `encodedPassword` format is an OCPP AuthorizationKey encoded as hexadecimal text (typically 32-40 hex characters).  If you want default password handling, use `/chargers/{chargerId}/ocpp/settings/password` instead.
- [Onboard charger: set installation to OCPP 1.6J authentication mode and configure URL](https://docs.zaptec.com/reference/post_chargers-chargerid-onboarding.md): Onboards a charger for OCPP by updating the charger's installation authentication mode to OCPP using the provided `ocppUrl`.  If `chargeBoxId` is provided, the endpoint also updates the charger setting for ChargeBoxId.  Limitations and considerations: - `ocppUrl` must be a valid WebSocket URL (`ws://` or `wss://`). - The charger must be linked to an installation.
- [Update OCPP URL for a charger](https://docs.zaptec.com/reference/put_chargers-chargerid-ocpp-settings.md): Updates the OCPP URL for a charger by switching the charger's installation to OCPP mode with the provided `ocppUrl`.  Limitations and considerations: - `ocppUrl` must be a valid WebSocket URL (`ws://` or `wss://`). - The charger must be linked to an installation.
- [Enable OCPP mode for an installation](https://docs.zaptec.com/reference/put_installations-installationid-mode-ocpp.md): Enables OCPP authentication mode for an installation.  Expected request payload: - `ocppUrl`: required OCPP central system URL.  Limitations and considerations: - `ocppUrl` is required. - This operation sets Zaptec load balancing on the installation to `false`.
- [Enable OCPP cloud mode for an installation](https://docs.zaptec.com/reference/put_installations-installationid-mode-ocpp-cloud.md): Enables OCPP cloud authentication mode for an installation.  Expected request payload: - `ocppUrl`: required OCPP cloud URL. - `ocppInitialChargePointPassword`: initial charge point password used by chargers. - `ocppDefaultIdTag`: default OCPP idTag used for authorization.  Limitations and considerations: - `ocppUrl` is required.
- [Enable Zaptec mode for an installation](https://docs.zaptec.com/reference/put_installations-installationid-mode-zaptec.md): Enables Zaptec authentication mode for an installation.  Optional request payload fields: - `requireAuthorization`: whether charger authorization is required. - `disableAuthorizationWhenOffline`: whether authorization should be disabled when offline.  Limitations and considerations: - Both request fields are optional and are forwarded as provided.

## Changelog
- [Zaptec Pro OCPP 1.6J (box-level) release notes](https://docs.zaptec.com/changelog/zaptec-pro-ocpp-16jbox-level-release-notes.md)
- [Zaptec Go 2 OCPP 1.6J(box-level) release notes](https://docs.zaptec.com/changelog/zaptec-go-2-ocpp-16jbox-level-release-notes.md)
- [Zaptec Go OCPP 1.6J(box-level) release notes](https://docs.zaptec.com/changelog/zaptec-go-ocpp-native-release-notes.md)
- [Zaptec Sense Firmware changelogs:](https://docs.zaptec.com/changelog/zaptec-sense-firmware-changelogs.md)
- [Zaptec PRO Firmware changelogs:](https://docs.zaptec.com/changelog/zaptec-pro-firmware-changelogs.md)
- [Zaptec GO and Zaptec GO 2 Firmware changelogs:](https://docs.zaptec.com/changelog/zaptec-go-and-zaptec-go-2-firmware-changelogs.md)
- [OCPP1.6J Cloud  Changelogs:](https://docs.zaptec.com/changelog/cloud-ocppbridge-changelogs.md)
- [API Changelogs:](https://docs.zaptec.com/changelog/testing.md)