{ "endpoints": [ { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/change-availability", "method": "POST", "operationId": "chargePointChangeAvailability", "summary": "Charge Point / Change Availability", "description": "change the availability to available or unavailable. A Charge Point is considered unavailable when it does not allow any charging.", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "evseNetworkId": { "type": "integer", "description": "The id of the connector for which availability needs to change. If missing the availability of the Charge Point and all its connectors needs to change." }, "type": { "type": "string", "enum": [ "Inoperative", "Operative" ], "description": "the type of availability change that the Charge Point should perform * `Inoperative` Charge point is not available for charging. * `Operative` Charge point is available for charging." } }, "required": [ "type" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "204": { "description": "Action scheduled. Request has been accepted and will be executed when transaction(s) in progress have finished." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected by the Charge Point" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/change-owner", "method": "POST", "operationId": "chargePointChangeOwner", "summary": "Charge Point / Change Owner", "description": "Change the owner of the Charge Point", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "integer", "nullable": true, "description": "This User would become the owner of the personal charge point. If left empty - no Owner would be assigned." } } } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/check-tariff-display-support", "method": "POST", "operationId": "chargePointCheckTariffDisplaySupport", "summary": "Charge Point / Check Tariff Display Support", "description": "Sends a DataTransfer probe to check whether the charge point supports tariff and cost display messages. If supported, the feature can be enabled automatically based on the request parameter. This action is only available for OCPP 1.6 charge points that do not have the CustomDisplayCostAndPrice configuration key set to true, and are not roaming or demo charge points.", "tags": [ "action / charge point" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enableIfSupported": { "type": "boolean", "default": true, "description": "If true, enables the tariff display capability when the charge point responds with Accepted." } } } } } }, "responses": { "202": { "description": "Action accepted - charge point supports tariff display" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Charge point does not support tariff display" }, "408": { "description": "Request timeout - the charge point did not respond within the expected time" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/clear-cache", "method": "POST", "operationId": "chargePointClearCache", "summary": "Charge Point / Clear cache", "description": "Clear cache of a charge point", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 255, "description": "Human-readable reason for clearing the cache. Used for audit logging purposes." } }, "required": [ "reason" ] } } } }, "responses": { "202": { "description": "Clear cache request accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected by the charge point" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/clear-charging-profile", "method": "POST", "operationId": "chargePointClearChargingProfile", "summary": "Charge Point / Clear Charging Profile", "description": "If you are not using networkId and not passing other criteria in the body it will clear the charging profile for the charge point (ChargePointMaxProfile). If you are using evse_network_id you will clear the charging profile just for that evse (TxDefaultProfile)", "tags": [ "action / charge point" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "The ID of the charging profile to clear." }, "evseNetworkId": { "type": "string", "description": "Specifies the ID of the connector for which to clear charging profiles. A connectorId of zero (0) specifies the charging profile for the overall Charge Point. Absence of this parameter means the clearing applies to all charging profiles that match the other criteria in the request." }, "chargingProfilePurpose": { "type": "string", "description": "Specifies to purpose of the charging profiles that will be cleared, if they meet the other criteria in the request." }, "stackLevel": { "type": "number", "description": "Specifies the stackLevel for which charging profiles will be cleared, if they meet the other criteria in the request." } } } } } }, "responses": { "202": { "description": "Clear request accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected by the Charge Point" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/disconnect", "method": "POST", "operationId": "chargePointDisconnect", "summary": "Charge Point / Disconnect", "description": "Disconnect a charge point", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 255, "description": "Human-readable reason for disconnecting the charge point. Used for audit logging purposes." } }, "required": [ "reason" ] } } } }, "responses": { "202": { "description": "Disconnect request accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/get-composite-schedule", "method": "POST", "operationId": "chargePointGetCompositeSchedule", "summary": "Charge Point / Get Composite Schedule", "description": "Request the composite charging schedule from a charge point. When evseNetworkId is omitted, returns the combined schedule at grid connection level (connectorId=0).", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "evseNetworkId": { "type": "integer", "description": "Connector to query. When omitted, returns the combined schedule at grid connection level (connectorId=0)." }, "duration": { "type": "integer", "description": "Length of the requested schedule in seconds." } }, "required": [ "duration" ] }, "example": { "evseNetworkId": 1, "duration": 3600 } } } }, "responses": { "202": { "description": "Action accepted - returns the composite schedule" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "The requested operation is not supported by the target device (e.g., the charge point does not implement the required feature)" }, "408": { "description": "Request timeout - the target did not respond within the expected time" }, "422": { "description": "The payload you provided is invalid" }, "424": { "description": "The requested operation cannot be completed because it depends on communication with an external system (e.g., charge point) that is currently disconnected or unreachable" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/get-diagnostics", "method": "POST", "operationId": "chargePointGetDiagnostics", "summary": "Charge Point / Get Diagnostics", "description": "Request a get diagnostics upload from the charge point. When `location` is omitted, the upload destination configured on the charge point's operator is used, extended with a folder named after the charge point manufacturer, and the operator's default reason, retries and retry interval are applied. If the operator has no diagnostics upload destination configured, the request is rejected with `412 Precondition Failed`.", "tags": [ "action / charge point" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "string", "description": "URL where the charge point will upload the diagnostics file. Any scheme the charge point supports is accepted - FTP, FTPS, HTTP or HTTPS. Optional - when omitted, the upload destination configured on the operator is used instead." }, "start": { "type": "string", "format": "date-time", "description": "Only get diagnostics that are created after this date-time" }, "stop": { "type": "string", "format": "date-time", "description": "Only get diagnostics that are created before that date-time" } } }, "examples": { "ftp": { "value": { "location": "ftp://user:password@example.com/path/to/store/logs", "start": "2020-07-21T00:00:00.000Z" } }, "https": { "value": { "location": "https://example.com/diagnostics/upload", "start": "2020-07-21T00:00:00.000Z" } }, "operatorUploadDestination": { "value": { "start": "2020-07-21T00:00:00.000Z" } }, "operatorUploadDestinationNoWindow": { "value": {} } } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected by the Charge Point" }, "412": { "description": "A precondition for performing this action is not met. The response message states which precondition failed." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/get-local-list-version", "method": "POST", "operationId": "chargePointGetLocalListVersion", "summary": "Charge Point / Get Local List Version", "description": "Request the current version number of the local authorization list from a charge point.", "tags": [ "action / charge point" ], "responses": { "200": { "description": "Success - returns the current local list version (greater than 0)" }, "204": { "description": "The charge point supports local authorization lists, but no list has been set" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "The requested operation is not supported by the target device (e.g., the charge point does not implement the required feature)" }, "408": { "description": "Request timeout - the target did not respond within the expected time" }, "422": { "description": "The payload you provided is invalid" }, "424": { "description": "The requested operation cannot be completed because it depends on communication with an external system (e.g., charge point) that is currently disconnected or unreachable" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/get-security-log", "method": "POST", "operationId": "chargePointGetSecurityLog", "summary": "Charge Point / Get Security Log", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "url", "description": "The URL of the location at the remote system where the log should be stored." }, "reason": { "type": "string", "description": "Reason kept in the action logs for future reference." }, "retries": { "type": "integer", "minimum": 0, "maximum": 10, "description": "This specifies how many times the Charge Point must try to upload the log before giving up. If this field is not present, it is left to Charge Point to decide how many times it wants to retry." }, "interval": { "type": "integer", "minimum": 0, "maximum": 3600, "description": "The interval in seconds after which a retry may be attempted. If this field is not present, it is left to Charge Point to decide how long to wait between attempts." }, "startTime": { "type": "string", "description": "This contains the date and time of the oldest logging information to include in the diagnostics. Please provide the value in the following format `Y-m-d H:i:s`." }, "stopTime": { "type": "string", "description": "This contains the date and time of the latest logging information to include in the diagnostics. Please provide the value in the following format `Y-m-d H:i:s`." } }, "required": [ "url", "reason" ] } } } }, "responses": { "201": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "404": { "description": "The record is not found" }, "406": { "description": "Action Rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/move-evses-to-satellite", "method": "POST", "operationId": "chargePointMoveEvsesToSatellite", "summary": "Charge Point / Move EVSEs to Satellite", "description": "Move one or more EVSEs from this charge point to a satellite charge point", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "satelliteChargePointId": { "type": "integer" }, "evseIds": { "type": "array", "items": { "type": "integer" } } }, "required": [ "satelliteChargePointId", "evseIds" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/reserve/{evse}", "method": "POST", "operationId": "chargePointReserve", "summary": "Charge Point / Reserve", "description": "Reserve an evse", "tags": [ "action / charge point" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "integer" }, "reason": { "type": "string", "description": "In case reason is empty, following text \"Activated via API\" will be added automatically" } }, "required": [ "userId" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected by the Charge Point" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/reset-security-profile", "method": "POST", "operationId": "chargePointResetSecurityProfile", "summary": "Charge Point / Reset Security Profile", "description": "Reset the current security profile of the charge point in the backend. The next time the charge point connects, the backend will accept the connection and update the current security profile with the one that the charge point actually used to establish the connection", "tags": [ "action / charge point" ], "responses": { "202": { "description": "Action succeeded" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/reset/{type}", "method": "POST", "operationId": "chargePointReset", "summary": "Charge Point / Reset", "description": "Reset a charge point", "tags": [ "action / charge point" ], "responses": { "202": { "description": "Reset request accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/send-custom-ocpp", "method": "POST", "operationId": "chargePointSendCustomOcpp", "summary": "Charge Point / Send Custom OCPP Command", "description": "Send a custom OCPP message to a charge point. This is a synchronous endpoint that waits for the charge point response or timeout. The raw response from the charge point is returned without transformation.", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "command": { "type": "string", "description": "OCPP command name (e.g., \"GetConfiguration\", \"TriggerMessage\", \"SetChargingProfile\")" }, "payload": { "type": "object", "additionalProperties": true, "description": "JSON payload matching the OCPP specification structure. May be omitted for OCPP commands that take no payload, such as `ClearCache` and `GetLocalListVersion`; omitting it sends the command with an empty payload (`{}`). An explicit `null` is rejected with a validation error." } }, "required": [ "command" ] }, "example": { "command": "GetConfiguration", "payload": { "key": [ "MeterValueSampleInterval" ] } } } } }, "responses": { "200": { "description": "Success - returns the raw response from the charge point" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "408": { "description": "Request timeout - the target did not respond within the expected time" }, "422": { "description": "The payload you provided is invalid" }, "424": { "description": "The requested operation cannot be completed because it depends on communication with an external system (e.g., charge point) that is currently disconnected or unreachable" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/send-data-transfer", "method": "POST", "operationId": "chargePointSendDataTransfer", "summary": "Charge Point / Send Data Transfer", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorId": { "type": "string", "description": "The identifier of the vendor specific implementation." }, "messageId": { "type": "string", "nullable": true, "description": "Additional identification field." }, "data": { "type": "string", "nullable": true, "description": "Data without specified length or format" } }, "required": [ "vendorId" ] } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected by the Charge Point" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/set-charging-profile/{evseNetworkId}", "method": "POST", "operationId": "chargePointSetChargingProfile", "summary": "Charge Point / Set Charging Profile", "description": "Set a smart charging profile", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionId": { "type": "integer" }, "stackLevel": { "type": "integer" }, "chargingProfilePurpose": { "type": "string", "enum": [ "ChargePointMaxProfile", "TxDefaultProfile", "TxProfile" ] }, "chargingProfileKind": { "type": "string", "enum": [ "Absolute", "Recurring", "Relative" ] }, "recurrencyKind": { "type": "string", "enum": [ "Daily", "Weekly" ] }, "validFrom": { "type": "string", "format": "date-time" }, "validTo": { "type": "string", "format": "date-time" }, "chargingSchedule": { "type": "object", "properties": { "id": { "type": "number", "nullable": true }, "duration": { "type": "integer" }, "startSchedule": { "type": "string", "format": "date-time" }, "chargingRateUnit": { "type": "string", "enum": [ "A", "W" ], "additionalProperties": false }, "chargingSchedulePeriod": { "type": "array", "items": { "type": "object", "properties": { "startPeriod": { "type": "integer" }, "limit": { "type": "number" }, "numberPhases": { "type": "integer" } }, "required": [ "startPeriod", "limit" ] } }, "minChargingRate": { "type": "number" } }, "required": [ "chargingRateUnit", "chargingSchedulePeriod" ] } }, "required": [ "stackLevel", "chargingProfilePurpose", "chargingProfileKind", "chargingSchedule" ], "description": "the smart charging profile to apply. See the OCPP documentation for further explanation on the fields" } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected by the Charge Point" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/start", "method": "POST", "operationId": "chargePointStartChargingSessionWithoutEvse", "summary": "Charge Point / Start Charging Session Without EVSE", "description": "Start a charging session", "tags": [ "action / charge point" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "integer" }, "paymentMethodId": { "type": "string", "nullable": true, "description": "The ID of the payment method, as returned by the payment method listing (User / Payment Method / Listing). When left empty or null, it would be determined by the system - either \"balance\" or \"subscription\" (in case the the user has an active post-paid subscription for home charging sessions and the charge point is a home charger). When it is NOT empty or null, userId is required." }, "externalSessionId": { "type": "string", "nullable": true, "description": "Deprecated: This field will be removed in version 2.0. Use `idTag` parameter instead. Migration: Replace all occurrences of `externalSessionId` with `idTag` in your start session requests. The `idTag` parameter serves the same purpose and stores the value in the session's `idTag` field. Backward compatibility: When both `externalSessionId` and `idTag` are provided, `idTag` takes precedence." }, "idTag": { "type": "string", "description": "Optional identifier tag for the charging session (e.g., RFID UID, authorization token). This value will be stored in the session's `idTag` field and can be used for filtering sessions. For operator-initiated sessions, the system also looks for a matching RFID card within the resolved operator's card list and links it to the session when found. If no matching card is found, the session remains unlinked and the submitted value remains available in the Business Data session export." }, "connectorId": { "type": "integer", "nullable": true }, "bookingId": { "type": "integer", "nullable": true, "description": "The ID of the booking to link the session to. Returns a 422 error if the booking does not exist or if its status is not Accepted or Reserved." }, "stopConditions": { "type": "object", "properties": { "maxEnergyKwh": { "type": "number", "minimum": 0.1, "nullable": true, "description": "Maximum energy consumption in kWh. Session will stop when this limit is reached. When both session-level and tariff-level limits exist, the lower value is enforced." }, "maxDurationMinutes": { "type": "integer", "minimum": 1, "nullable": true, "description": "Maximum session duration in minutes. Session will stop after this time. When both session-level and tariff-level limits exist, the lower value is enforced." }, "maxSocPercent": { "type": "integer", "minimum": 1, "maximum": 100, "nullable": true, "description": "Maximum state of charge percentage. Session will stop when this SoC is reached. When both session-level and tariff-level limits exist, the lower value is enforced." }, "maxAmount": { "type": "number", "minimum": 0.01, "nullable": true, "description": "Maximum cost allowed. Session will stop when charges reach this amount." } }, "nullable": true, "description": "Optional session stop conditions. When set, the session will automatically stop when any of the specified limits is reached." } }, "description": "Start session request body" } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/start/{evse}", "method": "POST", "operationId": "chargePointStartChargingSession", "summary": "Charge Point / Start Charging Session", "description": "Start a charging session", "tags": [ "action / charge point" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "integer" }, "paymentMethodId": { "type": "string", "nullable": true, "description": "The ID of the payment method, as returned by the payment method listing (User / Payment Method / Listing). When left empty or null, it would be determined by the system - either \"balance\" or \"subscription\" (in case the the user has an active post-paid subscription for home charging sessions and the charge point is a home charger). When it is NOT empty or null, userId is required." }, "externalSessionId": { "type": "string", "nullable": true, "description": "Deprecated: This field will be removed in version 2.0. Use `idTag` parameter instead. Migration: Replace all occurrences of `externalSessionId` with `idTag` in your start session requests. The `idTag` parameter serves the same purpose and stores the value in the session's `idTag` field. Backward compatibility: When both `externalSessionId` and `idTag` are provided, `idTag` takes precedence." }, "idTag": { "type": "string", "description": "Optional identifier tag for the charging session (e.g., RFID UID, authorization token). This value will be stored in the session's `idTag` field and can be used for filtering sessions. For operator-initiated sessions, the system also looks for a matching RFID card within the resolved operator's card list and links it to the session when found. If no matching card is found, the session remains unlinked and the submitted value remains available in the Business Data session export." }, "connectorId": { "type": "integer", "nullable": true }, "bookingId": { "type": "integer", "nullable": true, "description": "The ID of the booking to link the session to. Returns a 422 error if the booking does not exist or if its status is not Accepted or Reserved." }, "stopConditions": { "type": "object", "properties": { "maxEnergyKwh": { "type": "number", "minimum": 0.1, "nullable": true, "description": "Maximum energy consumption in kWh. Session will stop when this limit is reached. When both session-level and tariff-level limits exist, the lower value is enforced." }, "maxDurationMinutes": { "type": "integer", "minimum": 1, "nullable": true, "description": "Maximum session duration in minutes. Session will stop after this time. When both session-level and tariff-level limits exist, the lower value is enforced." }, "maxSocPercent": { "type": "integer", "minimum": 1, "maximum": 100, "nullable": true, "description": "Maximum state of charge percentage. Session will stop when this SoC is reached. When both session-level and tariff-level limits exist, the lower value is enforced." }, "maxAmount": { "type": "number", "minimum": 0.01, "nullable": true, "description": "Maximum cost allowed. Session will stop when charges reach this amount." } }, "nullable": true, "description": "Optional session stop conditions. When set, the session will automatically stop when any of the specified limits is reached." }, "chargingProfile": { "type": "object", "properties": { "transactionId": { "type": "integer" }, "stackLevel": { "type": "integer" }, "chargingProfilePurpose": { "type": "string", "enum": [ "ChargePointMaxProfile", "TxDefaultProfile", "TxProfile" ] }, "chargingProfileKind": { "type": "string", "enum": [ "Absolute", "Recurring", "Relative" ] }, "recurrencyKind": { "type": "string", "enum": [ "Daily", "Weekly" ] }, "validFrom": { "type": "string", "format": "date-time" }, "validTo": { "type": "string", "format": "date-time" }, "chargingSchedule": { "type": "object", "properties": { "id": { "type": "number", "nullable": true }, "duration": { "type": "integer" }, "startSchedule": { "type": "string", "format": "date-time" }, "chargingRateUnit": { "type": "string", "enum": [ "A", "W" ], "additionalProperties": false }, "chargingSchedulePeriod": { "type": "array", "items": { "type": "object", "properties": { "startPeriod": { "type": "integer" }, "limit": { "type": "number" }, "numberPhases": { "type": "integer" } }, "required": [ "startPeriod", "limit" ] } }, "minChargingRate": { "type": "number" } }, "required": [ "chargingRateUnit", "chargingSchedulePeriod" ] } }, "required": [ "stackLevel", "chargingProfilePurpose", "chargingProfileKind", "chargingSchedule" ], "description": "the smart charging profile to apply. See the OCPP documentation for further explanation on the fields" } }, "description": "Start session request body" } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. The 429 on this endpoint can be returned by either of two independent throttles. Both set the `Retry-After` header, whose value is the number of seconds the client must wait before retrying. The response body contains only a human-readable `message`. ## Tenant rate limit The global per-tenant Public API rate limiter. Inspect the `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers and back off until the window resets. ## Session start cooldown Repeated failed remote-start attempts on the same EVSE by the same user activate a short cooldown that protects charge points from excessive retried start requests. While the cooldown is active, further session-start calls for that user/EVSE pair are rejected with a `429 Too Many Requests` response. **What triggers it.** Every failed remote-start attempt against an EVSE — for example, the charge point rejecting the start command, the start request timing out, the EVSE being occupied, or the EV not being connected to the EVSE — counts toward the cooldown for the `(user, EVSE)` pair that issued the request. Up to two consecutive failures keep the cooldown at the standard **30 seconds**; three or more escalate it to **120 seconds**. **Scope.** The cooldown is scoped strictly to the `(user, EVSE)` pair that produced the failures — other users on the same EVSE and the same user on a different EVSE are unaffected. Successful starts reset the cooldown counter for that pair." } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/stop/{session}", "method": "POST", "operationId": "chargePointStopChargingSession", "summary": "Charge Point / Stop Charging Session", "description": "Stop a charging session", "tags": [ "action / charge point" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "type": "boolean", "default": false, "description": "Use force=true when you want to end the session reguardless of the CP response" } } } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected by the Charge Point" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/sync-configuration", "method": "POST", "operationId": "chargePointSyncConfiguration", "summary": "Charge point / Sync configuration", "description": "Send a partial or full sync configuration request to the charge point. The response includes a requestId that you can monitor using the ChargePointSyncConfigurationNotification. Please note that calling this action should not be required, as each time the charge point boots the configuration is automatically synced. Under normal conditions it should be impossible for a configuration key to change at runtime without the central systems request.", "tags": [ "action / charge point" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "oneOf": [ { "type": "string", "enum": [ "AllowOfflineTxForUnknownId", "AuthorizationCacheEnabled", "AuthorizeRemoteTxRequests", "BlinkRepeat", "ClockAlignedDataInterval", "ConnectionTimeOut", "ConnectorPhaseRotation", "ConnectorPhaseRotationMaxLength", "GetConfigurationMaxKeys", "HeartbeatInterval", "LightIntensity", "LocalAuthorizeOffline", "LocalPreAuthorize", "MaxEnergyOnInvalidId", "MeterValuesAlignedData", "MeterValuesAlignedDataMaxLength", "MeterValuesSampledData", "MeterValuesSampledDataMaxLength", "MeterValueSampleInterval", "MinimumStatusDuration", "NumberOfConnectors", "ResetRetries", "StopTransactionOnEVSideDisconnect", "StopTransactionOnInvalidId", "StopTxnAlignedData", "StopTxnAlignedDataMaxLength", "StopTxnSampledData", "StopTxnSampledDataMaxLength", "SupportedFeatureProfiles", "SupportedFeatureProfilesMaxLength", "TransactionMessageAttempts", "TransactionMessageRetryInterval", "UnlockConnectorOnEVSideDisconnect", "WebSocketPingInterval", "LocalAuthListEnabled", "LocalAuthListMaxLength", "SendLocalListMaxLength", "ReserveConnectorZeroSupported", "ChargeProfileMaxStackLevel", "ChargingScheduleAllowedChargingRateUnit", "ChargingScheduleMaxPeriods", "ConnectorSwitch3to1PhaseSupported", "MaxChargingProfilesInstalled", "AuthorizationEnabled" ] }, { "type": "string" } ] }, "default": [], "description": "List of keys to request a get configuration for. Omit or pass empty array to request all available configuration keys." }, "reportBase": { "type": "string", "enum": [ "full_inventory", "configuration_inventory", "summary_inventory" ], "default": "full_inventory", "example": "full_inventory", "description": "Report base type requested for an OCPP 2.0.1 or OCPP 2.1 GetBaseReport operation. * `full_inventory` - The charge point returns all component variables except monitoring settings. * `configuration_inventory` - The charge point returns only variables the operator can set. * `summary_inventory` - The charge point returns availability state and active fault conditions." } } } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected by the charge point" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/trigger-message", "method": "POST", "operationId": "chargePointTriggerMessageChargePoint", "summary": "Charge Point / Trigger Message Charge Point", "description": "Trigger message to given Charge Point", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BootNotification", "DiagnosticsStatusNotification", "LogStatusNotification", "FirmwareStatusNotification", "PublishFirmwareStatusNotification", "Heartbeat", "MeterValues", "StatusNotification", "SignV2GCertificate", "SignChargingStationCertificate", "SignCombinedCertificate", "TransactionEvent" ], "description": "The type of the message to be triggered. Messages available only for 2.0.1 chargers - LogStatusNotification, PublishFirmwareStatusNotification, SignChargingStationCertificate, SignCombinedCertificate, TransactionEvent" } }, "required": [ "type" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v1.0/{chargePoint}/unlock/{evse}", "method": "POST", "operationId": "chargePointEvseUnlock", "summary": "Charge Point / EVSE / Unlock", "description": "Unlock an EVSE", "tags": [ "action / charge point" ], "responses": { "202": { "description": "Unlock request accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected by the Charge Point" }, "422": { "description": "The payload you provided is invalid or problem with processing the request has occurred" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v2.0/{chargePoint}/change-sharing-code", "method": "POST", "operationId": "chargePointChangeSharingCode", "summary": "Charge Point / Change sharing code", "description": "Change sharing code for the Charge Point", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sharingCode": { "type": "string", "description": "The sharing code which provides access to the personal charge point for other users aside from the owner. If left empty the current code will be deleted" } } } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v2.0/{chargePoint}/delete-certificate", "method": "POST", "operationId": "chargePointDeleteCertificate", "summary": "Charge Point / Delete Certificate", "description": "Delete certificate", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificateType": { "type": "string", "enum": [ "ChargingStationCertificate", "V2GCertificate", "V2GRootCertificate", "MORootCertificate", "CSMSRootCertificate", "ManufacturerRootCertificate", "V2GCertificateChain" ], "description": "Indicates the type of certificate that is to be installed on the CP." } }, "required": [ "certificateType" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "Feature disabled for the system" }, "406": { "description": "Action rejected by the Charge Point" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" }, "501": { "description": "Action not implemented" } } }, { "path": "/public-api/actions/charge-point/v2.0/{chargePoint}/install-certificate", "method": "POST", "operationId": "chargePointInstallCertificate", "summary": "Charge Point / Install Certificate", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificateType": { "type": "string", "enum": [ "V2GRootCertificate", "MORootCertificate", "CSMSRootCertificate", "ManufacturerRootCertificate", "CentralSystemRootCertificate" ], "description": "Indicates the type of certificate that is to be installed on the CP." } }, "required": [ "certificateType" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "Feature disabled for the system" }, "406": { "description": "Action rejected by the Charge Point" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" }, "501": { "description": "Action not implemented" } } }, { "path": "/public-api/actions/charge-point/v2.0/{chargePoint}/set-configuration", "method": "POST", "operationId": "chargePointSetConfiguration", "summary": "Charge Point / Set Configuration", "description": "Set Configuration for the Charge Point", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "Value to be assigned to specific configuration key" }, "name": { "type": "string", "description": "Name of the variable of the configuration key" }, "instance": { "type": "string", "description": "Specify instance for OCPP 2.0.1 configuration keys" }, "componentName": { "type": "string", "description": "Required in order to specify component name for OCPP 2.0.1 configuration keys" }, "evseId": { "type": "integer", "description": "ID of the EVSE. Only for OCPP 2.0.1 configuration keys" } }, "required": [ "value", "name" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v2.0/{chargePoint}/set-security-profile", "method": "POST", "operationId": "chargePointSetSecurityProfile", "summary": "Charge Point / Set Security Profile", "description": "Set the security profile of the charge point. This operation installs Amazon root certificates (RSA & EC) and attempts to raise the security profile to the specified level. Only allows raising the profile (transitions 0→1, 0→2, 1→2), not lowering it.", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "setSecurityProfile": { "type": "integer", "enum": [ 1, 2 ], "description": "Target security profile level: - 1: Unsecured transport with basic authentication (plain-text authentication) - 2: TLS with basic authentication (encrypted authentication)" }, "reason": { "type": "string", "maxLength": 500, "description": "Free text reason for changing the security profile" } }, "required": [ "setSecurityProfile", "reason" ] } } } }, "responses": { "202": { "description": "Action accepted and is being processed asynchronously" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Invalid transition - occurs when: - Attempting to lower the security profile (e.g., 2→1, 2→0, 1→0) - Attempting to set the same security profile level (e.g., 1→1, 2→2) - Charge point does not support security profiles (max_security_profile is null) - Requested level exceeds the charge point's maximum supported security profile" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/charge-point/v2.0/{chargePoint}/sync-certificates", "method": "POST", "operationId": "chargePointGetInstalledCertificateIds", "summary": "Charge Point / Get Installed Certificate IDs", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificateType": { "type": "string", "enum": [ "V2GRootCertificate", "MORootCertificate", "CSMSRootCertificate", "V2GCertificateChain", "ManufacturerRootCertificate" ], "nullable": true, "description": "Indicates the type of certificates requested. Default value to be empty - the system should interpret the Null/empty value that all certificate types are requested." } } } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "Feature disabled for the system" }, "406": { "description": "Action rejected by the Charge Point" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" }, "501": { "description": "Action not implemented" } } }, { "path": "/public-api/actions/charge-point/v2.0/{chargePoint}/update-firmware", "method": "POST", "operationId": "chargePointUpdateFirmware", "summary": "Charge Point / Update Firmware", "tags": [ "action / charge point" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Location (URL) from which to retrieve the firmware. Either this or `firmwareVersionId` must be provided. URLs longer than 512 characters are rejected by charge points using signed firmware updates or OCPP 2.0.1; such requests fail with a `406` response and no command is sent to the charge point." }, "firmwareVersionId": { "type": "integer", "description": "ID of a Firmware Version. Either this or `url` must be provided." }, "retrieveAfter": { "type": "string", "format": "date-time", "description": "Specifies the date and time after which the Charge Point should retrieve the new firmware. If not provided, the current *datetime* will be used." }, "retries": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Specifies how many times the Charge Point must try to retrieve the (new) firmware before giving up." }, "interval": { "type": "integer", "minimum": 0, "maximum": 3600, "description": "The interval in seconds between each retry." }, "signed": { "type": "boolean", "description": "Indicates a Signed Firmware Update." }, "signingCertificate": { "type": "string", "description": "Required if \"signed\" is true." }, "signature": { "type": "string", "description": "Required if \"signed\" is true." }, "downloadUrlProtocol": { "type": "string", "enum": [ "http", "https" ], "description": "Protocol to use for the firmware download URL when using firmware repository. Use HTTP only if the charge point does not support encrypted connections." } }, "required": [ "signed" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected by the Charge Point, or the firmware URL exceeds 512 characters for a signed firmware update or an OCPP 2.0.1 charge point." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/circuit/v2.0/{circuit}/attach-charge-point", "method": "POST", "operationId": "circuitAttachChargePoint", "summary": "Circuit / Attach Charge Point", "description": "To maintain safety and compatibility, only charge points with an identical electrical configuration to the circuit can be added.", "tags": [ "action / circuit" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chargePointId": { "type": "integer" }, "priority": { "type": "number", "format": "float", "minimum": 0 } }, "required": [ "chargePointId" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/circuit/v2.0/{circuit}/detach-charge-point/{chargePoint}", "method": "POST", "operationId": "circuitDetachChargePoint", "summary": "Circuit / Detach Charge Point", "tags": [ "action / circuit" ], "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/circuit/v2.0/{circuit}/set-charge-point-priority/{chargePoint}", "method": "POST", "operationId": "circuitSetChargePointPriority", "summary": "Circuit / Set Charge Point Priority", "tags": [ "action / circuit" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priority": { "type": "number", "format": "float", "minimum": 0 } }, "required": [ "priority" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/circuit/v2.0/{circuit}/set-charge-point-priority/{chargePoint}/evse/{evse}", "method": "POST", "operationId": "circuitSetChargePointEvsePriority", "summary": "Circuit / Set Charge Point EVSE Priority", "tags": [ "action / circuit" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priority": { "type": "number", "format": "float", "minimum": 0 } }, "required": [ "priority" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/circuit/v2.0/{circuit}/set-circuit-soc-priorities", "method": "POST", "operationId": "circuitSetCircuitSocPriority", "summary": "Circuit / Set Circuit SoC Priority", "description": "Set DLM priority based on the session's state of charge (SoC). The active priority will be used to either decrease or increase the energy used by the session's EVSE. - If the SoC exceeds the `upperThresholdPercent`, then the `highSoCPriority` will be applied. - If the SoC is below the `lowerThresholdPercent`, then the `lowSoCPriority` will be applied. - If neither of the above conditions is true, then the priority is set to 1. You can provide either the `upperThresholdPercent` with the `highSoCPriority` or the `lowerThresholdPercent` with the `lowSoCPriority` or both pairs. When a lower or upper threshold is not set, the default priority of 1 will be used.", "tags": [ "action / circuit" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "upperThresholdPercent": { "type": "number", "minimum": 5, "maximum": 95, "nullable": true, "description": "The state of charge (SoC) percentage above which the `highSoCPriority` will be applied. Must have a 5% offset from the `lowerThresholdPercent` (if provided). For example if `lowerThresholdPercent` is set to 50, this can have a value of 55 or higher. Setting this to `null` will remove the usage of the `highSoCPriority`." }, "highSoCPriority": { "type": "number", "format": "float", "minimum": 0 }, "lowerThresholdPercent": { "type": "number", "minimum": 5, "maximum": 95, "nullable": true, "description": "The state of charge (SoC) percentage below which the `lowSoCPriority` will be applied. Must have a 5% offset from the `upperThresholdPercent` (if provided). For example if `upperThresholdPercent ` is set to 50, this can have a value of 45 or lower. Setting this to `null` will remove the usage of the `lowSoCPriority`." }, "lowSoCPriority": { "type": "number", "format": "float", "minimum": 0 } } } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/circuit/v2.0/{circuit}/set-session-boost/{session}", "method": "POST", "operationId": "circuitSetSessionBoost", "summary": "Circuit / Set Session Boost", "description": "Sets the per-session DLM boost flag for an active session. When enabled, the boosted EVSE receives the unused headroom between the active circuit constraint (schedule limit and/or flexibility request) and the circuit's maximum capacity, capped at the EVSE's maximum supported current. The change applies on the next DLM algorithm tick. The flag persists for the remainder of the session. The boost ends when either the session ends (no explicit call required) or the client sends this action again with `enabled: false`. Sending the same value the session already carries is accepted as an idempotent no-op (returns 202 with no second effect). The action is rejected with HTTP 422 if the session is not in the active state.", "tags": [ "action / circuit" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true, "description": "Whether the DLM boost is active for this session. The action is rejected with HTTP 422 if the session is not active; sending the same value the session already carries is accepted as an idempotent no-op." } }, "required": [ "enabled" ], "description": "Request body for the set-session-boost circuit action." } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/circuit/v2.0/{circuit}/set-session-priority/{session}", "method": "POST", "operationId": "circuitSetSessionPriority", "summary": "Circuit / Set Session Priority", "tags": [ "action / circuit" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priority": { "type": "number", "format": "float", "minimum": 0 } }, "required": [ "priority" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/configuration-template/v1.0/{template}/apply-to-charge-points", "method": "POST", "operationId": "configurationTemplateApplyToChargePoints", "summary": "Configuration Template / Apply to Charge Points", "description": "Apply a configuration template to charge points.", "tags": [ "action / configuration template" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chargePointIds": { "type": "array", "items": { "type": "integer" }, "description": "Array of charge point IDs the template will be applied to." }, "shouldPersist": { "type": "boolean", "default": false, "description": "Specifies whether the configuration template will be enforced each time the charge point boots." }, "resetType": { "type": "string", "enum": [ "none", "soft", "hard" ], "default": "soft", "description": "Reset to perform after the configuration is pushed. `none` applies the configuration without restarting the charge point. `soft` restarts the charge point software (recommended default). `hard` power-cycles the charge point." } } } } } }, "responses": { "202": { "description": "Action accepted" }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/actions/configuration-template/v1.0/{template}/insert-bulk-variables", "method": "POST", "operationId": "configurationTemplateBulkCreateVariables", "summary": "Configuration Template / Bulk Create Variables", "description": "Create multiple variables for a specific configuration template, adds them to the already existing keys and validates if there are duplicates.", "tags": [ "action / configuration template" ], "parameters": { "path": { "template": { "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "keyName": { "type": "string" }, "value": { "type": "string" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "keyName", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "integer" }, "value": { "type": "string" }, "variableName": { "type": "string" }, "variableType": { "type": "string", "enum": [ "Actual", "Target", "MinSet", "MaxSet" ], "nullable": true }, "variableInstance": { "type": "string", "nullable": true }, "component": { "type": "string" }, "componentInstance": { "type": "string", "nullable": true }, "evseId": { "type": "integer", "nullable": true }, "connectorId": { "type": "integer", "nullable": true }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "value", "variableName", "component" ], "additionalProperties": false, "description": "Represents a configuration variable based on the OCPP 2.0.1 specification. Fields such as `variableName`, `variableType`, `variableInstance`, `component`, `componentInstance`, `evseId`, and `connectorId` directly correspond to the OCPP 2.0.1 protocol." } ] } } } } }, "responses": { "200": { "description": "Configuration Template Variables created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/actions/electricity-meter/v1.0/{electricityMeter}/report-consumption", "method": "POST", "operationId": "electricityMeterReportConsumption", "summary": "Electricity Meter / Report Consumption", "description": "Add an electricity meter report for the meter readings at the current moment", "tags": [ "action / electricity meter" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "The timestamp of the measurements. ISO 8601 formatted date." }, "currentL1": { "type": "integer", "minimum": 0, "maximum": 5000000, "description": "The current on L1 in milliamperes (mA)" }, "currentL2": { "type": "integer", "minimum": 0, "maximum": 5000000, "description": "The current on L2 in milliamperes (mA)" }, "currentL3": { "type": "integer", "minimum": 0, "maximum": 5000000, "description": "The current on L3 in milliamperes (mA)" } } } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/energy-coupon-template/v1.0/{energyCouponTemplate}/deactivate", "method": "POST", "operationId": "energyCouponTemplateDeactivate", "summary": "Energy coupon template / Deactivate", "description": "Deactivate an energy coupon template by setting its status to expired. No new redemptions will be possible. Existing coupons are not affected. Only templates with status active, paused or expired can be deactivated.", "tags": [ "action / energy coupon template" ], "responses": { "202": { "description": "Template deactivation accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "Template cannot be deactivated because its current status does not allow it" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/energy-coupon/v1.0/redeem-code", "method": "POST", "operationId": "energyCouponRedeemCode", "summary": "Energy coupon / Redeem code", "description": "Redeem a coupon or template code for a specific user.", "tags": [ "action / energy coupon" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "The coupon or template redemption code" }, "userId": { "type": "integer", "description": "The ID of the user to redeem the coupon for. Must belong to the API key operator." } }, "required": [ "code", "userId" ], "description": "Payload for redeeming an energy coupon by code" } } } }, "responses": { "200": { "description": "Coupon redeemed successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "User-group restriction not met (user does not belong to an allowed user group)." }, "404": { "description": "Possible errors: * Invalid code (no coupon or template exists with this code) * User not found (no user with this ID within the API token's operator scope) * Feature flag disabled" }, "409": { "description": "Possible errors: * Coupon has already been redeemed * Redemption rule violated (`once_per_user`, `once_per_email`, `once_per_phone_number`, `once_per_device`, `new_users_only`)" }, "410": { "description": "Template has expired (status)." }, "412": { "description": "Template's validity window has passed." }, "423": { "description": "Template is paused and cannot be redeemed." }, "424": { "description": "Template is exhausted (max redemptions reached)." }, "425": { "description": "Template is not yet active (its validity window starts in the future)." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/energy-coupon/v1.0/{energyCoupon}/cancel", "method": "POST", "operationId": "energyCouponCancel", "summary": "Energy coupon / Cancel", "description": "Permanently cancels an energy coupon, setting its status to `cancelled`. Any remaining energy on the coupon is forfeited and can no longer be used for charging sessions. Coupons that are currently locked (actively being used in a charging session) cannot be cancelled.", "tags": [ "action / energy coupon" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional reason for cancellation" } } } } } }, "responses": { "202": { "description": "Energy coupon cancellation accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The coupon is currently locked (actively being used in a charging session) and cannot be cancelled" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/evse/v1.0/bulk-assign-tariff-group", "method": "POST", "operationId": "evseBulkAssignTariffGroups", "summary": "EVSEs / Bulk Assign Tariff Groups", "description": "Bulk assign tariff groups for multiple EVSEs. This action allows you to assign or unassign tariff groups to multiple EVSEs at once, filtered by location, partner, evses and tariff groups. The update is processed synchronously and there is a limit of max 1000 EVSEs per request.", "tags": [ "action / evse" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "locationIds": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ], "description": "Filter EVSEs by location IDs" }, "partnerIds": { "type": "array", "items": { "type": "integer" }, "example": [ 10, 20 ], "description": "Filter EVSEs by partner IDs" }, "evseIds": { "type": "array", "items": { "type": "integer" }, "example": [ 10, 20 ], "description": "Filter EVSEs by EVSE IDs" }, "chargePointIds": { "type": "array", "items": { "type": "integer" }, "example": [ 10, 20 ], "description": "Filter EVSEs by Charge point IDs" }, "tariffGroupIds": { "type": "array", "items": { "type": "integer" }, "example": [ 10, 20 ], "description": "Filter EVSEs by tariff group IDs" } }, "description": "Optional filters to select EVSEs for bulk update" }, "tariffGroupId": { "type": "integer", "example": 42, "nullable": true, "description": "The tariff group ID to assign (null to unassign)" } }, "required": [ "tariffGroupId" ], "example": { "filters": { "locationIds": [ 1, 2 ], "partnerIds": [ 10 ], "evseIds": [ 10, 20 ], "chargePointIds": [ 10, 20 ], "tariffGroupIds": [ 10 ] }, "tariffGroupId": 42 } } } } }, "responses": { "202": { "description": "Action accepted" }, "204": { "description": "Action scheduled. Request has been accepted and will be executed when transaction(s) in progress have finished." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected by the Charge Point" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/evse/v1.0/{evse}/start", "method": "POST", "operationId": "evseStartChargingWithEvseId", "summary": "EVSE / Start Charging with EVSE ID", "description": "Start a charging session", "tags": [ "action / evse" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "integer" }, "paymentMethodId": { "type": "string", "nullable": true, "description": "The ID of the payment method, as returned by the payment method listing (User / Payment Method / Listing). When left empty or null, it would be determined by the system - either \"balance\" or \"subscription\" (in case the the user has an active post-paid subscription for home charging sessions and the charge point is a home charger). When it is NOT empty or null, userId is required." }, "externalSessionId": { "type": "string", "nullable": true, "description": "Deprecated: This field will be removed in version 2.0. Use `idTag` parameter instead. Migration: Replace all occurrences of `externalSessionId` with `idTag` in your start session requests. The `idTag` parameter serves the same purpose and stores the value in the session's `idTag` field. Backward compatibility: When both `externalSessionId` and `idTag` are provided, `idTag` takes precedence." }, "idTag": { "type": "string", "description": "Optional identifier tag for the charging session (e.g., RFID UID, authorization token). This value will be stored in the session's `idTag` field and can be used for filtering sessions. For operator-initiated sessions, the system also looks for a matching RFID card within the resolved operator's card list and links it to the session when found. If no matching card is found, the session remains unlinked and the submitted value remains available in the Business Data session export." }, "connectorId": { "type": "integer", "nullable": true }, "bookingId": { "type": "integer", "nullable": true, "description": "The ID of the booking to link the session to. Returns a 422 error if the booking does not exist or if its status is not Accepted or Reserved." }, "stopConditions": { "type": "object", "properties": { "maxEnergyKwh": { "type": "number", "minimum": 0.1, "nullable": true, "description": "Maximum energy consumption in kWh. Session will stop when this limit is reached. When both session-level and tariff-level limits exist, the lower value is enforced." }, "maxDurationMinutes": { "type": "integer", "minimum": 1, "nullable": true, "description": "Maximum session duration in minutes. Session will stop after this time. When both session-level and tariff-level limits exist, the lower value is enforced." }, "maxSocPercent": { "type": "integer", "minimum": 1, "maximum": 100, "nullable": true, "description": "Maximum state of charge percentage. Session will stop when this SoC is reached. When both session-level and tariff-level limits exist, the lower value is enforced." }, "maxAmount": { "type": "number", "minimum": 0.01, "nullable": true, "description": "Maximum cost allowed. Session will stop when charges reach this amount." } }, "nullable": true, "description": "Optional session stop conditions. When set, the session will automatically stop when any of the specified limits is reached." }, "chargingProfile": { "type": "object", "properties": { "transactionId": { "type": "integer" }, "stackLevel": { "type": "integer" }, "chargingProfilePurpose": { "type": "string", "enum": [ "ChargePointMaxProfile", "TxDefaultProfile", "TxProfile" ] }, "chargingProfileKind": { "type": "string", "enum": [ "Absolute", "Recurring", "Relative" ] }, "recurrencyKind": { "type": "string", "enum": [ "Daily", "Weekly" ] }, "validFrom": { "type": "string", "format": "date-time" }, "validTo": { "type": "string", "format": "date-time" }, "chargingSchedule": { "type": "object", "properties": { "id": { "type": "number", "nullable": true }, "duration": { "type": "integer" }, "startSchedule": { "type": "string", "format": "date-time" }, "chargingRateUnit": { "type": "string", "enum": [ "A", "W" ], "additionalProperties": false }, "chargingSchedulePeriod": { "type": "array", "items": { "type": "object", "properties": { "startPeriod": { "type": "integer" }, "limit": { "type": "number" }, "numberPhases": { "type": "integer" } }, "required": [ "startPeriod", "limit" ] } }, "minChargingRate": { "type": "number" } }, "required": [ "chargingRateUnit", "chargingSchedulePeriod" ] } }, "required": [ "stackLevel", "chargingProfilePurpose", "chargingProfileKind", "chargingSchedule" ], "description": "the smart charging profile to apply. See the OCPP documentation for further explanation on the fields" } }, "description": "Start session request body" } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. The 429 on this endpoint can be returned by either of two independent throttles. Both set the `Retry-After` header, whose value is the number of seconds the client must wait before retrying. The response body contains only a human-readable `message`. ## Tenant rate limit The global per-tenant Public API rate limiter. Inspect the `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers and back off until the window resets. ## Session start cooldown Repeated failed remote-start attempts on the same EVSE by the same user activate a short cooldown that protects charge points from excessive retried start requests. While the cooldown is active, further session-start calls for that user/EVSE pair are rejected with a `429 Too Many Requests` response. **What triggers it.** Every failed remote-start attempt against an EVSE — for example, the charge point rejecting the start command, the start request timing out, the EVSE being occupied, or the EV not being connected to the EVSE — counts toward the cooldown for the `(user, EVSE)` pair that issued the request. Up to two consecutive failures keep the cooldown at the standard **30 seconds**; three or more escalate it to **120 seconds**. **Scope.** The cooldown is scoped strictly to the `(user, EVSE)` pair that produced the failures — other users on the same EVSE and the same user on a different EVSE are unaffected. Successful starts reset the cooldown counter for that pair." } } }, { "path": "/public-api/actions/evse/v1.0/{evse}/trigger-message", "method": "POST", "operationId": "evseTriggerMessage", "summary": "EVSE / Trigger Message", "description": "Trigger message to given EVSE", "tags": [ "action / evse" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BootNotification", "DiagnosticsStatusNotification", "LogStatusNotification", "FirmwareStatusNotification", "PublishFirmwareStatusNotification", "Heartbeat", "MeterValues", "StatusNotification", "SignV2GCertificate", "SignChargingStationCertificate", "SignCombinedCertificate", "TransactionEvent" ], "description": "The type of the message to be triggered. Messages available only for 2.0.1 chargers - LogStatusNotification, PublishFirmwareStatusNotification, SignChargingStationCertificate, SignCombinedCertificate, TransactionEvent" } }, "required": [ "type" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/flexibility-asset/v1.0/{flexibilityAsset}/change-status", "method": "POST", "operationId": "changeFlexibilityAssetStatus", "summary": "Flexibility Asset / Change Status", "description": "Change the status of the Flexibility Asset", "tags": [ "action / flexibility asset" ], "parameters": { "path": { "flexibilityAsset": { "description": "ID of the Flexibility Asset", "type": "string", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "endsAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. If an end date is set the asset will be automatically disabled at that time. Historical time series and forecasts are not generated after the end date." } }, "required": [ "status" ] } } } }, "responses": { "201": { "description": "The status of the Asset is changed" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/flexibility-asset/v1.0/{flexibilityAsset}/create-activation-request", "method": "POST", "operationId": "flexibilityAssetCreateActivationRequest", "summary": "Flexibility Asset / Create Activation Request", "description": "Create Flexibility Activation Request for a specific Asset", "tags": [ "action / flexibility asset" ], "parameters": { "path": { "flexibilityAsset": { "description": "ID of the Flexibility Asset", "type": "string", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "periods": { "type": "array", "items": { "type": "object", "properties": { "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" }, "energy": { "type": "integer", "format": "int64", "description": "The target energy (Wh) that the system should achieve during the specified time period. Only one is required: maxPower or energy." }, "maxPower": { "type": "integer", "format": "int64", "description": "The target power (W) that the system should achieve during the specified time period. Only one is required: maxPower or energy." } }, "required": [ "startTime", "endTime" ] } } } } } } }, "responses": { "201": { "description": "Flexibility Activation Request created for the Asset" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/id-tag/v1.0/{idTag}/reissue-emaid", "method": "POST", "operationId": "certificateReissueAnEmaid", "summary": "Certificate / Reissue an EMAID", "tags": [ "action / certificate" ], "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "Feature disabled for the system" }, "406": { "description": "Action rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" }, "501": { "description": "Action not implemented" } } }, { "path": "/public-api/actions/installer-job/v1.0/{installerJob}/assign-charge-points", "method": "POST", "operationId": "assignInstallerJobChargePoints", "summary": "Actions / Assign Charge Points", "description": "Assign charge points to an installer job", "tags": [ "action / installer job" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chargePointIds": { "type": "array", "items": { "type": "integer" }, "description": "List of charge point IDs to be assigned to the installer job, if passed chargingZoneId and locationId will be ignored" }, "chargingZoneId": { "type": "integer", "description": "The ID of the charging zone, if passed and chargePointIds are not provided, all the charge points in the specified charging zone will be assigned to the installer job and locationId will be ignored" }, "locationId": { "type": "integer", "description": "The ID of the location, if passed and neither chargePointIds nor chargingZoneId are provided, all charge points in the specified location will be assigned to the installer job" } } } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected, possible reason could be if none of locationId, chargingZoneId or chargePointIds is provided" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/installer-job/v1.0/{installerJob}/change-status", "method": "POST", "operationId": "changeInstallerJobStatus", "summary": "Actions / Change Status", "description": "Change the status of an installer job", "tags": [ "action / installer job" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "new", "in_progress", "completed", "failed" ], "description": "The status of the installer job" }, "outcomeDetails": { "type": "string", "description": "The outcome details of the installer job, ignored if the status is not \"completed\" or \"failed\"" } }, "required": [ "status" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected, possible reason could be if if the existing status is already the same as provided" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/invoice/v1.0/{invoice}/update-external-id", "method": "POST", "operationId": "invoiceUpdateExternalId", "summary": "Invoice / Update External ID", "description": "Update the external ID reference for an invoice. This allows linking the invoice to an external accounting or ERP system.", "tags": [ "action / invoice" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "Reference identifier from external accounting or ERP system. Set to null or empty string to clear." } }, "required": [ "externalId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/locations/v2.0/{location}/check-booking-availability", "method": "POST", "operationId": "locationCheckBookingAvailability", "summary": "Location / Check Booking Availability", "description": "Get a consolidated view of EVSEs availability for a given location and time frame. Returns available time slots for each bookable EVSE at the location.", "tags": [ "action / location" ], "parameters": { "path": { "location": { "description": "Location ID", "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "startAfter": { "type": "string", "format": "date-time", "description": "Start of the time frame to check" }, "endBefore": { "type": "string", "format": "date-time", "description": "End of the time frame to check. Time-frame is limited to 7 days." } }, "required": [ "startAfter", "endBefore" ], "description": "Request for checking booking availability at a location" } } } }, "responses": { "200": { "description": "Availability check successful" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/notifications/v1.0/{notification}/resend", "method": "POST", "operationId": "notificationsResendFailed", "summary": "Notifications / Resend Failed", "description": "Resend failed webhook notifications. - Resend for a specific notification ID can be requested once every 15 minutes. - Notifications that are disabled cannot be resent. - Each failed notification will be resent only once. If it fails again, it will be added back to the failed notifications list.", "tags": [ "action / notifications" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "string", "enum": [ "AuthorizationNotification", "authorization.changed", "BootNotification", "ChargePointChangedNotification", "chargePoint.changed", "evse.changed", "ChargePointSyncConfigurationNotification", "CircuitConsumptionNotification", "circuit.changed", "DiagnosticsStatusNotification", "FirmwareStatusNotification", "HardwareStatusNotification", "LocationChangedNotification", "NetworkStatusNotification", "SecurityEventNotification", "SessionMeterValuesNotification", "SessionStartStopNotification", "session.start.stop.notification", "SessionUpdateNotification", "session.chargingPeriod.changed", "UserChangedNotification", "SubOperatorChangedNotification", "TariffChangedNotification", "tariffGroup.changed", "user.subscriptionChanged", "user.subscription.changed", "ReservationChangedNotification", "PaymentMethodChangedNotification", "PartnerInviteChangedNotification", "reservation.changed", "user.paymentMethod.changed", "userBalance.changed", "partnerInvite.changed", "partnerInviteCorporateBillingPolicy.changed", "roamingPlatform.changed", "parkingSpace.occupancyStatus.changed", "partner.changed", "transaction.changed", "settlementReport.created", "idTag.changed", "issue.changed", "chargePoint.dataTransferReceived", "subscriptionPlan.changed", "user.invoiceDetails.changed", "cdr.received", "chargingProfile.applied", "installerJob.changed", "corporateBilling.limitReached" ] } }, "startTime": { "type": "string", "format": "datetime", "description": "Resend all failed notifications from this date onwards." }, "endTime": { "type": "string", "format": "datetime", "description": "Resend all failed notifications up to this date." } }, "required": [ "notifications" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/parking-spaces/v1.0/{parkingSpace}/update-occupancy-status", "method": "POST", "operationId": "parkingSpaceUpdateOccupancyStatus", "summary": "Parking Space / Update occupancy status", "tags": [ "action / parking space" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "occupied", "blocked" ], "description": "Target occupancy status for the parking space: - **available**: Parking space is free and ready for use - **occupied**: Parking space is currently in use - **blocked**: Parking space is physically blocked (roadworks, barriers, planned maintenance)" } }, "required": [ "status" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "Feature disabled for the system" }, "406": { "description": "Action rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" }, "501": { "description": "Action not implemented" } } }, { "path": "/public-api/actions/partner-invite-corporate-billing-policy/v1.0/{corporateBillingPolicy}/disable", "method": "POST", "operationId": "partnerInviteCorporateBillingPolicyDisable", "summary": "Partner invite corporate billing policy / Disable", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Disable a partner invite corporate billing policy.", "tags": [ "action / partner invite corporate billing policy" ], "responses": { "202": { "description": "Accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/partner-invite-corporate-billing-policy/v1.0/{corporateBillingPolicy}/enable", "method": "POST", "operationId": "partnerInviteCorporateBillingPolicyEnable", "summary": "Partner invite corporate billing policy / Enable", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Enable a partner invite corporate billing policy.", "tags": [ "action / partner invite corporate billing policy" ], "responses": { "202": { "description": "Accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/partner-invoice/v1.0/{partnerInvoice}/issue-credit-note", "method": "POST", "operationId": "partnerInvoiceIssueCreditNote", "summary": "Partner invoice / Issue credit note", "description": "Issue a full credit note cancelling the given partner invoice. The credit note copies the original's seller, buyer, currency and payment terms, negates every line item, is marked paid, and references the cancelled invoice via `referenceId`. Only one credit note may exist per invoice. Issuing returns the linked settlement report to `ready_to_invoice`. Partial credit notes are not supported. Eligibility depends on the B2B invoice processor recorded on the invoice at issuance. An invoice generated through the built-in B2B invoice integration is eligible as soon as it is issued. An invoice generated through a processor that certifies documents with a fiscal authority is eligible only after the original document has been certified — until the document exists at the fiscal authority there is nothing to cancel. Use `fiscalization.status` on the single-invoice read to observe this: `pending` and `failed` mean not yet creditable, `certified` means the precondition is met. Certification is a necessary, not a sufficient, condition — the rare certified document with no recorded `fiscalization.referenceNumber` described under `fiscalization.status` stays ineligible and requires operator intervention. A `425` means the original document has not been certified with the fiscal authority yet, so there is nothing to cancel. Retry once `fiscalization.status` on the single-invoice read reaches `certified`.", "tags": [ "action / partner invoice" ], "responses": { "202": { "description": "Accepted - the response body contains the newly created credit note" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The invoice is permanently ineligible for credit note issuance and the request will not succeed on retry. Returned when the invoice already has a credit note, when the target is itself a credit note, when the B2B invoice processor recorded on the invoice does not support credit note issuance, or when the original document is certified but its fiscal authority number was never recorded on the platform." }, "425": { "description": "The original document is not yet certified with the fiscal authority. The invoice becomes creditable once `fiscalization.status` reaches `certified`." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/partner-invoice/v1.0/{partnerInvoice}/update-external-id", "method": "POST", "operationId": "partnerInvoiceUpdateExternalId", "summary": "Partner invoice / Update external ID", "description": "Update or clear the external invoice reference ID for a partner invoice. Used for integration with external accounting systems.", "tags": [ "action / partner invoice" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "An optional external identifier for integration purposes" } }, "required": [ "externalId" ] } } } }, "responses": { "202": { "description": "Accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/partner-settlement-report/v1.0/{partnerSettlementReport}/issue-partner-invoice", "method": "POST", "operationId": "partnerSettlementReportIssuePartnerInvoice", "summary": "Partner settlement report / Issue partner invoice", "description": "This action validates the given settlement report and accepts it for partner invoice generation. The settlement report must have a B2B invoice processor configured on its operator and must not already have been invoiced. Both balance directions are eligible. When expenses are greater than or equal to revenue, the action produces a regular partner invoice on which the operator is the seller. When expenses are lower than revenue, the balance is in the partner's favor and the action produces a self-billing invoice on which the partner is the seller. Invoice generation runs asynchronously after the request is accepted; the `202` confirms acceptance of the request, not the outcome. Poll the settlement report read endpoint: - **Generated** — `partnerInvoiceId` is present and identifies the new partner invoice. - **Not generated** — generation failed after acceptance. No partner invoice record exists and `partnerInvoiceId` remains absent. Causes include a missing or invalid tax identification number on the partner, a report currency the operator's B2B invoice processor does not support, a tax rate not configured on that processor, and a report whose invoiceable total nets to zero. The failure is reported to the operator through the platform; poll with a bounded number of attempts rather than indefinitely. Where the operator's B2B invoice processor certifies documents with a fiscal authority, `partnerInvoiceId` appearing means the invoice **record** exists — not that a legally issued document exists. Certification runs as a second asynchronous stage; read `fiscalization.status` on the single-invoice endpoint to follow it to `certified` or `failed`.", "tags": [ "action / partner settlement report" ], "responses": { "202": { "description": "Accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/partner-settlement-report/v1.0/{partnerSettlementReport}/set-custom-fields", "method": "POST", "operationId": "partnerSettlementReportSetCustomFields", "summary": "Partner settlement report / set custom fields", "description": "⚠️ Experimental endpoint — not yet a stable contract. This action ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Set the applicable live custom field values of a partner settlement report without changing the historical report, its generated documents, party and settings snapshots, or derived partner invoices. This action requires permission to view the partner settlement report and the `PartnerSettlementReports.update-custom-fields` permission. The `customFields` object accepts Boolean, Text, Long text, Email, URL, Number, Date, Date-time and JSON values according to each administrator-defined field. It may be empty. Omitted identifiers remain unchanged, while an explicit `null` clears the corresponding value. Every submitted identifier is validated against the report's current partner owner, the current custom field configuration and the acting administrator's access. Unknown, inapplicable or currently disabled identifiers return a `422` error keyed as `customFields.`, and no submitted values are changed. This write action does not accept query parameters or includes. The response is the current default read representation after applying the values; `customFields` remains live metadata and is not a point-in-time representation of the historical settlement report.", "tags": [ "action / partner settlement report" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customFields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by their administrator-defined identifiers. The accepted type for each identifier is defined by the tenant's custom field configuration. Boolean values are JSON booleans; text and long text values are strings; email values are email-formatted strings; URL values are HTTP or HTTPS URL strings; number values use canonical base-10 decimal strings from `-99999999999999.999999` through `99999999999999.999999` with up to six fractional digits and no insignificant trailing fractional zeroes; date values are ISO 8601 `YYYY-MM-DD` strings; date-time values are ISO 8601 timestamps with a UTC offset; and JSON values may use any JSON-serializable value. Decimal strings are the precision-safe number request representation. JSON numeric inputs remain accepted for compatibility, but their precision may depend on the client's number handling." } }, "required": [ "customFields" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted - the response body contains the partner settlement report's default current read representation after applying the submitted values" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/partner-settlement-report/v1.0/{partnerSettlementReport}/update-external-id", "method": "POST", "operationId": "partnerSettlementReportUpdateExternalId", "summary": "Partner Settlement Report / Update External ID", "description": "Update or clear the external invoice reference ID for a partner settlement report. Used for integration with external accounting systems.", "tags": [ "action / partner settlement report" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "External invoice or reference ID for integration with external accounting systems. Set to null or empty string to clear." } }, "required": [ "externalId" ] } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/partner/v1.0/{partner}/set-custom-fields", "method": "POST", "operationId": "partnerSetCustomFieldsV1_0", "summary": "Partner / set custom fields", "description": "⚠️ Experimental endpoint — not yet a stable contract. This action ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Set the applicable custom field values of a partner without changing any other partner properties. This action requires permission to view the partner and the `Partners.update-custom-fields` permission. Send a JSON object containing only the required `customFields` property. Query parameters and additional body properties are rejected. The `customFields` object may be empty. Omitted identifiers remain unchanged, while an explicit `null` clears the corresponding value. Every submitted identifier is validated against the partner, the current custom field configuration and the acting administrator's access. Unknown, inapplicable or currently disabled identifiers return a `422` error keyed as `customFields.`, and no submitted values are changed.", "tags": [ "action / partner" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customFields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by their administrator-defined identifiers. The accepted type for each identifier is defined by the tenant's custom field configuration. Boolean values are JSON booleans; text and long text values are strings; email values are email-formatted strings; URL values are HTTP or HTTPS URL strings; number values use canonical base-10 decimal strings from `-99999999999999.999999` through `99999999999999.999999` with up to six fractional digits and no insignificant trailing fractional zeroes; date values are ISO 8601 `YYYY-MM-DD` strings; date-time values are ISO 8601 timestamps with a UTC offset; and JSON values may use any JSON-serializable value. Decimal strings are the precision-safe number request representation. JSON numeric inputs remain accepted for compatibility, but their precision may depend on the client's number handling." } }, "required": [ "customFields" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted - the response body contains the partner's default v2.0 read representation after applying the submitted values" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/payment-terminal/v1.0/{paymentTerminal}/set-custom-fields", "method": "POST", "operationId": "paymentTerminalSetCustomFields", "summary": "Payment terminal / set custom fields", "description": "⚠️ Experimental endpoint — not yet a stable contract. This action ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Set the applicable custom field values of a payment terminal without changing any other payment terminal properties. This action requires permission to view the payment terminal and the `PaymentTerminals.update-custom-fields` permission. When custom fields are enabled for payment terminals, the `customFields` object may be empty; an empty object succeeds as a no-op without creating a value audit. Omitted identifiers remain unchanged, while an explicit `null` clears the corresponding value. If custom fields are disabled for the tenant or for payment terminals, an empty object returns a `422` error keyed as `customFields`, while a populated object returns errors keyed as `customFields.`. Every submitted identifier is validated against the payment terminal, the current custom field configuration and the acting administrator's access. Unknown or inapplicable identifiers also return a `422` error keyed as `customFields.`, and no submitted values are changed.", "tags": [ "action / payment terminal" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customFields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by their administrator-defined identifiers. The accepted type for each identifier is defined by the tenant's custom field configuration. Boolean values are JSON booleans; text and long text values are strings; email values are email-formatted strings; URL values are HTTP or HTTPS URL strings; number values use canonical base-10 decimal strings from `-99999999999999.999999` through `99999999999999.999999` with up to six fractional digits and no insignificant trailing fractional zeroes; date values are ISO 8601 `YYYY-MM-DD` strings; date-time values are ISO 8601 timestamps with a UTC offset; and JSON values may use any JSON-serializable value. Decimal strings are the precision-safe number request representation. JSON numeric inputs remain accepted for compatibility, but their precision may depend on the client's number handling." } }, "required": [ "customFields" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted - the response body contains the payment terminal's v1.1 read representation after applying the submitted values" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/provisioning-certificate/v1.0/{provisioningCertificate}/issue-emaid", "method": "POST", "operationId": "certificateIssueAnEmaid", "summary": "Certificate / Issue an EMAID", "tags": [ "action / certificate" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethod": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `defaultPaymentOption` instead.** The payment method that will be associated with the EMAID Tag. * For **credit/debit cards** provide the payment method ID as a string (e.g. `\"5\"`) * For **Corporate billing** - `corporate:{id}` * For **Subscription** - use `\"subscription\"` to use the user's active subscription * For **Auto selection** - use `\"auto\"` (recommended) or `null` (deprecated) * The \"last used\" concept has been replaced with \"auto\" selection which cycles through available payment methods. **Precedence:** when both `defaultPaymentOption` and `paymentMethod` are provided, `defaultPaymentOption` wins. **Fallback:** if both are omitted, the EMAID is issued with `\"auto\"`." }, "defaultPaymentOption": { "type": "string", "example": "auto", "description": "The default payment option for this ID tag. Accepted values: * `auto` - Automated fallback sequence * A payment card ID - Specific registered payment card * `corporate:{id}` - Corporate billing account (replace {id} with the corporate billing ID) * `subscription` - User's active post-paid subscription At charging time, if the chosen payment option doesn't apply to the session (e.g., corporate billing not eligible for the charge point, subscription not applicable), the platform falls back to the user's other available payment methods." } } } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "Feature disabled for the system" }, "406": { "description": "Action rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" }, "501": { "description": "Action not implemented" } } }, { "path": "/public-api/actions/reimbursement-record/v1.0/{reimbursementRecord}/issue-credit", "method": "POST", "operationId": "reimbursementRecordIssueCredit", "summary": "Reimbursement record / Issue credit", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Creates and returns a new reimbursement record with negated amounts that reverses the original record. A record that is already reversed, or is itself a reversing record, cannot be reversed again. This is not an accounting credit note against an invoice — reimbursement records are stateless computed entries, so a credit is the reimbursement-domain analogue of a correcting entry.", "tags": [ "action / reimbursement record" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "creditReason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Reason for issuing the credit." } }, "required": [ "creditReason" ] } } } }, "responses": { "201": { "description": "Credit record created" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/reimbursement-report/v1.0/{reimbursementReport}/regenerate", "method": "POST", "operationId": "reimbursementReportRegenerate", "summary": "Reimbursement report / Regenerate", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Discards the report and rebuilds it from the current reimbursement records on the next generation run. The discarded report id no longer resolves after regeneration; fetch the replacement from the reports listing (its constituent records point to it via `filter[reportId]`). Processing is asynchronous — the response returns immediately with `202 Accepted`.", "tags": [ "action / reimbursement report" ], "responses": { "202": { "description": "Regeneration accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/reservation/v1.0/{reservation}/cancel", "method": "POST", "operationId": "reservationCancel", "summary": "Reservation / Cancel", "description": "Cancel a reservation", "tags": [ "action / reservation" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "type": "boolean", "default": false, "description": "Use force=true when you want to end the reservation regardless of the CP response" }, "reason": { "type": "string", "nullable": true, "description": "In case reason is empty, following text \"Activated via API\" will be added automatically" } } } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected by the Charge Point" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/roaming-emsp/v1.0/{roamingEmsp}/assign-partner", "method": "POST", "operationId": "roamingEmspAssignPartner", "summary": "Roaming EMSP / Assign Partner", "description": "Assign or clear the partner mapped to this Roaming EMSP for a platform operator. Send an integer `partnerId` to assign; send `null` to clear. Use `GET /resources/roaming-emsps/v1.0/{roamingEmsp}/partners` to read the current state.", "tags": [ "action / roaming emsp" ], "parameters": { "path": { "roamingEmsp": { "description": "The ID of the roaming EMSP", "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "description": "ID of the platform operator. Required for global admins; for operator-scoped admins it defaults to the caller's own operator." }, "partnerId": { "type": "integer", "nullable": true, "description": "ID of the partner to assign. Send `null` to clear the assignment." } }, "required": [ "partnerId" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/roaming-operator/v2.0/{roamingOperator}/custom-tariff-filter/{customTariffFilter}/set-pricing-data", "method": "POST", "operationId": "updateCustomTariffFilterTariff", "summary": "Custom Tariff Filters / Set Pricing Data", "description": "Set the pricing data for a custom tariff filter. This action will update the underlying roaming tariff and create a pricing based on it. The pricing can then be utilized by attaching a markup tariff to the tariff map of the custom tariff filter. The pricing data must follow the OCPI 2.2.1 Tariff object specification.", "tags": [ "action / roaming operator" ], "parameters": { "path": { "roamingOperator": { "description": "The ID of the roaming operator", "type": "integer", "example": 123, "required": true }, "customTariffFilter": { "description": "The ID of the custom tariff filter", "type": "integer", "example": 456, "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country_code": { "type": "string", "minLength": 2, "maxLength": 2, "example": "NL", "description": "ISO-3166 alpha-2 country code of the CPO that owns this Tariff." }, "party_id": { "type": "string", "minLength": 3, "maxLength": 3, "example": "ANY", "description": "ID of the CPO that owns this Tariff (following the ISO-15118 standard)." }, "id": { "type": "string", "maxLength": 36, "example": "12345", "description": "Uniquely identifies the tariff within the CPO's platform." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR", "description": "ISO 4217 code of the currency of this tariff." }, "type": { "type": "string", "enum": [ "AD_HOC_PAYMENT", "PROFILE_CHEAP", "PROFILE_FAST", "PROFILE_GREEN", "REGULAR" ], "description": "Type of this tariff." }, "tariff_alt_text": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string", "minLength": 2, "maxLength": 2, "example": "en", "description": "Language Code ISO 639-1." }, "text": { "type": "string", "maxLength": 512, "example": "Standard charging tariff", "description": "Alternative tariff text in this language." } }, "required": [ "language", "text" ] }, "description": "List of multi-language alternative texts for this tariff." }, "tariff_alt_url": { "type": "string", "format": "uri", "maxLength": 255, "example": "https://www.example.com/tariff-info", "description": "URL to a web page that contains an explanation of the tariff information." }, "min_price": { "type": "object", "properties": { "excl_vat": { "type": "number", "format": "float", "minimum": 0, "example": 10, "description": "Price excluding VAT." }, "incl_vat": { "type": "number", "format": "float", "minimum": 0, "example": 12.1, "description": "Price including VAT." } }, "description": "Price with VAT excluded and included." }, "max_price": { "type": "object", "properties": { "excl_vat": { "type": "number", "format": "float", "minimum": 0, "example": 10, "description": "Price excluding VAT." }, "incl_vat": { "type": "number", "format": "float", "minimum": 0, "example": 12.1, "description": "Price including VAT." } }, "description": "Price with VAT excluded and included." }, "elements": { "type": "array", "items": { "type": "object", "properties": { "price_components": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ENERGY", "FLAT", "PARKING_TIME", "TIME" ], "description": "Type of tariff dimension." }, "price": { "type": "number", "format": "float", "minimum": 0, "example": 0.25, "description": "Price per unit (excluding VAT) for this tariff dimension." }, "vat": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "example": 21, "description": "Applicable VAT percentage for this tariff dimension. If omitted, no VAT is applicable." }, "step_size": { "type": "integer", "minimum": 1, "example": 1, "description": "Minimum amount to be billed. This unit will be billed in this step_size." } }, "required": [ "type", "price", "step_size" ] }, "minItems": 1, "description": "List of price components that describe the pricing of this tariff element." }, "restrictions": { "type": "object", "properties": { "start_time": { "type": "string", "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$", "example": "08:00", "description": "Start time of day in local time, the time zone is defined in the location." }, "end_time": { "type": "string", "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$", "example": "18:00", "description": "End time of day in local time, the time zone is defined in the location." }, "start_date": { "type": "string", "format": "date", "example": "2024-01-01", "description": "Start date in local time, the time zone is defined in the location." }, "end_date": { "type": "string", "format": "date", "example": "2024-12-31", "description": "End date in local time, the time zone is defined in the location." }, "min_kwh": { "type": "number", "format": "float", "minimum": 0, "example": 0, "description": "Minimum consumed energy in kWh." }, "max_kwh": { "type": "number", "format": "float", "minimum": 0, "example": 50, "description": "Maximum consumed energy in kWh." }, "min_current": { "type": "number", "format": "float", "minimum": 0, "example": 16, "description": "Sum of the minimum current (in Amperes) over all phases." }, "max_current": { "type": "number", "format": "float", "minimum": 0, "example": 32, "description": "Sum of the maximum current (in Amperes) over all phases." }, "min_power": { "type": "number", "format": "float", "minimum": 0, "example": 0, "description": "Minimum power in kW." }, "max_power": { "type": "number", "format": "float", "minimum": 0, "example": 22, "description": "Maximum power in kW." }, "min_duration": { "type": "integer", "minimum": 0, "example": 0, "description": "Minimum duration in seconds." }, "max_duration": { "type": "integer", "minimum": 0, "example": 3600, "description": "Maximum duration in seconds." }, "day_of_week": { "type": "array", "items": { "type": "string", "enum": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ] }, "description": "Which day(s) of the week this tariff element is active." }, "reservation": { "type": "string", "enum": [ "RESERVATION", "RESERVATION_EXPIRES" ], "description": "When this restriction is present, the tariff element applies to a reservation." } }, "description": "Restrictions that apply to this tariff element." } }, "required": [ "price_components" ] }, "minItems": 1, "description": "List of Tariff Elements." }, "start_date_time": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z", "description": "The time when this tariff becomes active. Format ISO 8601 UTC." }, "end_date_time": { "type": "string", "format": "date-time", "example": "2024-12-31T23:59:59Z", "description": "The time after which this tariff is no longer valid. Format ISO 8601 UTC." }, "energy_mix": { "type": "object", "properties": { "is_green_energy": { "type": "boolean", "example": true, "description": "True if 100% from regenerative sources." }, "energy_sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "NUCLEAR", "GENERAL_FOSSIL", "COAL", "GAS", "GENERAL_GREEN", "SOLAR", "WIND", "WATER" ], "description": "Type of energy source." }, "percentage": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "example": 40, "description": "Percentage of this source in the mix." } }, "required": [ "source", "percentage" ] }, "description": "Energy sources of this energy mix." }, "environ_impact": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "NUCLEAR_WASTE", "CARBON_DIOXIDE" ], "description": "Environmental impact category." }, "amount": { "type": "number", "format": "float", "minimum": 0, "example": 120, "description": "Amount of this impact in g/kWh." } }, "required": [ "category", "amount" ] }, "description": "Environmental impact of this energy mix." }, "supplier_name": { "type": "string", "maxLength": 64, "example": "Green Energy Co", "description": "Name of the energy supplier." }, "energy_product_name": { "type": "string", "maxLength": 64, "example": "100% Wind Power", "description": "Name of the energy product." } }, "description": "Details about the energy mix." }, "last_updated": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z", "description": "Timestamp when this Tariff was last updated. Format ISO 8601 UTC." } }, "required": [ "id", "currency", "elements", "last_updated" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/session/v1.0/{session}/assign-user", "method": "POST", "operationId": "sessionAssignToUser", "summary": "Session / Assign to user", "description": "Assign a user to a session. This action is only applicable to sessions with Completed billing status that have no user associated with them. This operation can be done only once and is not reversible.", "tags": [ "action / session" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "integer" } }, "required": [ "userId" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "Conflict - The request cannot be completed due to a conflict with the current state of the resource. Possible errors: * Session billing status is not Completed * Session is not anonymous" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/session/v1.0/{session}/change-tariff", "method": "POST", "operationId": "sessionChangeTariff", "summary": "Session / Change tariff", "description": "Change the tariff for a session and trigger recalculation of charging periods. This action supports loyalty program integrations where discounts need to be applied mid-session. The tariff change is only available when: - Billing status is NOT \"Completed\" - For running sessions: duration is under 3 hours - For roaming sessions (Ampeco as eMSP): session must be finished and have a CDR received - No recalculation is already in progress - For local charge point sessions: a StartTransaction message must exist", "tags": [ "action / session" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tariffId": { "type": "integer", "description": "The ID of the tariff to apply to the session" } }, "required": [ "tariffId" ] } } } }, "responses": { "202": { "description": "Action accepted. The tariff has been changed and charging periods are being recalculated." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "Conflict - The request cannot be completed due to a conflict with the current state of the resource. Possible errors: * Billing is already completed for this session * Session duration exceeds 3 hours (running sessions only) * Roaming session without a CDR * Recalculation already in progress * StartTransaction message missing (local CP sessions)" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/session/v1.0/{session}/retry-payment", "method": "POST", "operationId": "sessionRetryPayment", "summary": "Session / Retry Payment", "description": "Retry failed payment for a session", "tags": [ "action / session" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethodId": { "type": "integer", "nullable": true } } } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "Conflict - The request cannot be completed due to a conflict with the current state of the resource. Possible errors: * Session payment cannot be retried - Payment status must be either 'failed' or 'partially paid' * Session total amount is below the minimum transaction amount required by the payment provider * Session billing status is not completed * Session is not finalized" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/session/v1.0/{session}/set-custom-fields", "method": "POST", "operationId": "sessionSetCustomFields", "summary": "Session / set custom fields", "description": "⚠️ Experimental endpoint — not yet a stable contract. This action ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Set the applicable custom field values of a session without changing any other session properties. This action requires permission to view the session and the `Sessions.update-custom-fields` permission. When custom fields are enabled for sessions, the `customFields` object may be empty; an empty object succeeds as a no-op without creating a value audit. Omitted identifiers remain unchanged, while an explicit `null` clears the corresponding value. If custom fields are disabled for the tenant or for sessions, an empty object returns a `422` error keyed as `customFields`, while a populated object returns errors keyed as `customFields.`. Every submitted identifier is validated against the session, the current custom field configuration and the acting administrator's access. Unknown or inapplicable identifiers also return a `422` error keyed as `customFields.`, and no submitted values are changed.", "tags": [ "action / session" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customFields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by their administrator-defined identifiers. The accepted type for each identifier is defined by the tenant's custom field configuration. Boolean values are JSON booleans; text and long text values are strings; email values are email-formatted strings; URL values are HTTP or HTTPS URL strings; number values use canonical base-10 decimal strings from `-99999999999999.999999` through `99999999999999.999999` with up to six fractional digits and no insignificant trailing fractional zeroes; date values are ISO 8601 `YYYY-MM-DD` strings; date-time values are ISO 8601 timestamps with a UTC offset; and JSON values may use any JSON-serializable value. Decimal strings are the precision-safe number request representation. JSON numeric inputs remain accepted for compatibility, but their precision may depend on the client's number handling." } }, "required": [ "customFields" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted - the response body contains the session's default read representation after applying the submitted values" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/subscription-plans/v1.0/{subscriptionPlan}/replace", "method": "POST", "operationId": "subscriptionPlanReplace", "summary": "Subscription plan / Replace", "description": "Replace a subscription plan with another one.", "tags": [ "action / subscription-plan" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "integer", "description": "The ID of the subscription plan that replaces the current one. The new Subscription plan will be added to the Subscription plans Restrictions for the Tariffs, where the old plan is present. Also it will be added to all Charge points that require the current Subscription plan." }, "replaceAt": { "type": "string", "format": "date-time", "nullable": true, "description": "The date from which the new Subscription Plan replaces the current one. If left empty, it is replaced immediately." }, "reason": { "type": "string", "description": "Internal note for tracking changes and the reasons for those changes." } }, "required": [ "planId", "reason" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/tariffs/v2.0/{tariff}/set-tariff-display-information", "method": "POST", "operationId": "tariffSetDisplayInformation", "summary": "Tariff / Set Display Information", "description": "Create or update tariff display information. This action supports both first-time creation and subsequent updates. **Field replacement behavior:** Every call fully replaces all four display text fields. Fields not included in the request body, or sent as `null`, are reset to empty. To retain an existing value, you must re-supply it in the request. **Deprecated fields:** The `defaultPriceInformation` and `defaultPriceInformationOffline` fields are deprecated. Use the tariff group resource to manage these fields instead. The scalar `priceInformation` and `totalCostInformation` fields are deprecated in favor of their `Localized` siblings, which support multi-locale round-tripping.", "tags": [ "action / tariff" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "defaultPriceInformation": { "type": "string", "maxLength": 150, "nullable": true, "description": "Deprecated: use the tariff group resource to manage this field." }, "defaultPriceInformationOffline": { "type": "string", "maxLength": 150, "nullable": true, "description": "Deprecated: use the tariff group resource to manage this field." }, "priceInformation": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `priceInformationLocalized` instead.** The scalar field only carries the default-locale value and cannot round-trip multi-locale content. The information that would be shown on the display of the charge point for users that are eligible for this tariff." }, "priceInformationLocalized": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "totalCostInformation": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `totalCostInformationLocalized` instead.** The scalar field only carries the default-locale value and cannot round-trip multi-locale content. Additional information that would be displayed on the charge point when the session ends, along with the total fees for energy, duration and idle." }, "totalCostInformationLocalized": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "plainTextModeEnabled": { "type": "boolean", "description": "When `true`, the display text is delivered to the charge point without rich text formatting." } } } } } }, "responses": { "200": { "description": "Tariff display information updated successfully" }, "201": { "description": "Tariff display information created successfully" }, "401": { "description": "Access token is missing or invalid" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/tax/v1.0/validate-vat", "method": "POST", "operationId": "validateTaxNumber", "summary": "Taxes / Validate VAT number", "description": "Validate an EU VAT ID against the official VIES (VAT Information Exchange System) API from the European Commission. Returns validation status along with company name and address when available. The service strips the country code prefix from the VAT number before validation if present (e.g., 'PL5252678750' becomes '5252678750' when validating for country 'PL').", "tags": [ "action / tax" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "example": "PL", "description": "Two-letter ISO country code (e.g., 'PL', 'DE', 'RO')" }, "vatNumber": { "type": "string", "example": "5252678750", "description": "VAT number to validate (may or may not include country code prefix)" } }, "required": [ "countryCode", "vatNumber" ] }, "example": { "countryCode": "PL", "vatNumber": "5252678750" } } } }, "responses": { "200": { "description": "VAT number is valid" }, "401": { "description": "Access token is missing or invalid" }, "404": { "description": "VAT number is invalid or does not exist" }, "422": { "description": "The payload you provided is invalid" }, "424": { "description": "VIES service is temporarily unavailable (external dependency failure)" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/transaction/v1.0/{transaction}/create-pre-authorization", "method": "POST", "operationId": "transactionCreatePreAuthorization", "summary": "Transaction / Create Pre-Authorization", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. Creates a pre-authorisation — a hold, never an immediate charge — for a pending ad hoc transaction, using the payment processor set on the transaction (Worldline, Stripe or Adyen), and returns what you need to collect the customer's payment. Amount and currency come from the transaction. Repeated calls return the existing pre-authorisation instead of creating a second one.", "tags": [ "action / transaction" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "processor": { "type": "string", "enum": [ "worldline" ], "description": "The payment processor of the transaction." }, "paymentProductId": { "type": "integer", "description": "Worldline payment product id selecting the payment rail (e.g. TWINT, Bancontact)." }, "returnUrl": { "type": "string", "description": "URL Worldline redirects the customer back to after completing the hosted-checkout page." }, "locale": { "type": "string", "description": "Locale used to render the Worldline hosted-checkout page (e.g. \"en\", \"de\")." }, "paymentProductFilters": { "type": "object", "properties": { "restrictTo": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "integer" } }, "groups": { "type": "array", "items": { "type": "string" } } }, "description": "Restrict the hosted-checkout page to the listed products and groups." }, "exclude": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "integer" } }, "groups": { "type": "array", "items": { "type": "string" } } }, "description": "Exclude the listed products and groups from the hosted-checkout page." } }, "description": "Optional Worldline payment-product restrictions applied to the hosted-checkout page." } }, "required": [ "processor", "returnUrl" ], "additionalProperties": false, "description": "Create-pre-authorization request for a transaction whose payment processor is Worldline. The pre-authorisation is created as a Worldline hosted-checkout page; the response returns the URL to redirect the customer to." }, { "type": "object", "properties": { "processor": { "type": "string", "enum": [ "stripe" ], "description": "The payment processor of the transaction." } }, "required": [ "processor" ], "additionalProperties": false, "description": "Create-pre-authorization request for a transaction whose payment processor is Stripe. No card details are sent in this request — the response returns a PaymentIntent client secret, and the customer's card is collected client-side (for example with Stripe Elements) to complete the pre-authorisation." }, { "type": "object", "properties": { "processor": { "type": "string", "enum": [ "adyen" ], "description": "The payment processor of the transaction." }, "returnUrl": { "type": "string", "description": "URL Adyen redirects the customer back to after completing the hosted checkout page." }, "locale": { "type": "string", "description": "Locale used to render the Adyen hosted checkout page and the 3DS challenge (e.g. \"en\", \"de\"). Optional — when omitted, the locale resolves to the transaction user's preferred language, and when the transaction has no user, to the locale of this request: the first Accept-Language entry naming a locale the platform supports, or the platform's configured default language when the header names none. English is used only when the resolved language is one Adyen does not support." } }, "required": [ "processor", "returnUrl" ], "additionalProperties": false, "description": "Create-pre-authorization request for a transaction whose payment processor is Adyen. The pre-authorisation is created as an Adyen Hosted Checkout session; the response returns the URL of the hosted checkout page to redirect the customer to." } ] } } } }, "responses": { "200": { "description": "The pre-authorisation was created, or already existed from an earlier call — repeated calls return the same payment data. The response contains what you need to collect the customer's payment." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "424": { "description": "The requested operation cannot be completed because it depends on communication with an external system (e.g., charge point) that is currently disconnected or unreachable" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/transactions/v1.0/{transaction}/issue-invoice", "method": "POST", "operationId": "transactionIssueInvoice", "summary": "Transaction / Issue Invoice", "description": "Issue ad-hoc invoice for the transaction (only if the platform's native invoice integration is used). For Számlázz.hu integration in Hungary, if a fiscalized receipt exists for the transaction, it will be automatically canceled and both the invoice and storno receipt will be sent to the user.", "tags": [ "action / transaction" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Conditionally required based on the Email field configuration in the operator's invoice integration. When omitted, the invoice is issued without sending an email notification." }, "locale": { "type": "string", "example": "en", "description": "ISO language code (e.g., \"en\", \"bg\", \"de\") for bilingual invoice generation. When \"Issue bilingual invoices\" is enabled for the operator, the invoice is generated in both the operator's configured invoice language (primary) and this locale (secondary). If not provided, falls back to: user's preferred locale → operator default → tenant default → English." }, "invoiceDetails": { "type": "object", "properties": { "invoiceType": { "type": "string", "enum": [ "individual", "company" ] }, "individualName": { "type": "string" }, "individualPersonalId": { "type": "string" }, "individualTaxId": { "type": "string" }, "companyName": { "type": "string" }, "companyRegNo": { "type": "string" }, "companyTaxId": { "type": "string" }, "companyTaxAdministrationOfficeName": { "type": "string" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "city": { "type": "string" }, "postCode": { "type": "string" }, "address": { "type": "string" }, "recipientCode": { "type": "string", "minLength": 7, "maxLength": 7, "pattern": "^[A-Za-z0-9]{7}$", "example": "ABC1234", "description": "Italian SDI recipient code of the buyer. Only collected when the operator uses the Avalara e-invoicing integration with an Italian mandate. Exactly seven alphanumeric characters; lowercase input is accepted and stored uppercased. An Italian company must supply at least one of `recipientCode` and `recipientCertifiedEmail`. Omit the property when there is no value to supply." }, "recipientCertifiedEmail": { "type": "string", "format": "email", "example": "buyer@pec.example.com", "description": "Certified electronic mail (PEC) address of the buyer. Only collected when the operator uses the Avalara e-invoicing integration with an Italian mandate. An Italian company must supply at least one of `recipientCode` and `recipientCertifiedEmail`. Omit the property when there is no value to supply." } }, "required": [ "invoiceType" ], "description": "Create user invoice details" } }, "required": [ "invoiceDetails" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "Invoice already issued. Use the `Resend Invoice` action to send the invoice again" }, "412": { "description": "The criteria for issuing an invoice have not been met - the transaction's user must be ad-hoc, the transaction's session must have been paid, and the on-demand window must not be overdue" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/transactions/v1.0/{transaction}/resend-invoice", "method": "POST", "operationId": "transactionResendInvoice", "summary": "Transaction / Resend Invoice", "description": "Resend already issued invoice. If the transaction has an associated fiscalized receipt that was automatically canceled (Hungary compliance), both the invoice and the storno receipt will be sent together.", "tags": [ "action / transaction" ], "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "Invoice not issued yet. Use the `Issue Invoice` action to issue an invoice" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/transactions/v1.0/{transaction}/update-payment-reference", "method": "POST", "operationId": "transactionUpdatePaymentReference", "summary": "Transaction / Update Payment Reference", "description": "Link the transaction to external resource where the payment took place.", "tags": [ "action / transaction" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ref": { "type": "string", "description": "Reference to the payment processor or payment terminal where more information about the transaction could be checked." } }, "required": [ "ref" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/user/v1.0/{user}/revoke-marketing-consent", "method": "POST", "operationId": "userRevokeMarketingConsent", "summary": "User / Revoke marketing consent", "description": "Revoke a single user's marketing consent. Records an admin-initiated entry in the consent audit log and an entry in the backend Actions log, attributed to the API token's admin. Use when acting on a GDPR opt-out request received outside the app. Idempotent: calling on a user who is already opted out returns 202, refreshes the 'receive news and promotions' updated-at timestamp, and records a new entry in the Actions log. The consent audit log only gains entries for consents whose state actually changes. Partner-scoped tokens: when a partner-scoped token targets a user outside the partner's visibility, the response is 403 (consistent with other user-action endpoints) — the user-edit ability is denied because the token's admin cannot act on the target user.", "tags": [ "action / user" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500, "description": "Optional note kept in the action audit log (e.g. ticket reference, support case ID, requester name)." } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/users/v1.0/{user}/activate-subscription", "method": "POST", "operationId": "userActivateSubscription", "summary": "User / Activate subscription", "description": "Activate a subscription to a user", "tags": [ "action / user" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "integer" }, "endDate": { "type": "string", "format": "date", "example": "2022-05-30", "nullable": true, "description": "The subscription will be valid until this end date" }, "autoRenewal": { "type": "boolean", "description": "Enable the auto-renewal of the subscription after the end date" }, "reason": { "type": "string", "nullable": true, "description": "In case reason is empty, following text \"Activated via API\" will be added automatically" } }, "required": [ "planId" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/users/v1.0/{user}/add-balance", "method": "POST", "operationId": "userAddBalance", "summary": "User / Add Balance", "description": "Add to the current balance of the user", "tags": [ "action / user" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number" }, "reason": { "type": "string" }, "app_info": { "type": "string", "maxLength": 2000 } }, "required": [ "amount", "reason" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Action accepted" }, "400": { "description": "Currency is not set." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/users/v1.0/{user}/apply-custom-fee", "method": "POST", "operationId": "userApplyCustomFee", "summary": "User / Apply Custom Fee", "description": "Apply custom fee for a user", "tags": [ "action / user" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "format": "decimal", "description": "The amount entered is tax-inclusive. The tax rate will be based on the EV driver’s operator default tax rate." }, "description": { "type": "string", "description": "Shown to the user and also added to the user's bank statement (if the payment method is a bank card)." }, "paymentMethodId": { "type": "string", "nullable": true, "description": "The ID of the payment method, as returned by the payment method listing (User / Payment Method / Listing). When left empty or null, it would take the balance and if the balance is insufficient, would reject the action. Corporate billing is not supported as a payment method." } }, "required": [ "amount", "description" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Action accepted" }, "400": { "description": "Currency is not set, Your card was declined or User has insufficient balance" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/users/v1.0/{user}/cancel-subscription", "method": "POST", "operationId": "userCancelSubscription", "summary": "User / Cancel subscription", "description": "Cancel a subscription to a user", "tags": [ "action / user" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "The reason for the cancellation. It would be included in the Audit logs." } }, "required": [ "reason" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/users/v1.0/{user}/change-status", "method": "POST", "operationId": "userChangeStatus", "summary": "User / Change Status", "description": "Set the status for a user", "tags": [ "action / user" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "* `enabled` Enabled - the user is allowed to use the system * `disabled` Disabled - the user is NOT allowed to use the system" }, "reason": { "type": "string" } }, "required": [ "status", "reason" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/users/v1.0/{user}/clear-subscription-amount-due", "method": "POST", "operationId": "userClearSubscriptionAmountDue", "summary": "User / Clear subscription amount due", "description": "Clear a user's subscription amount due. Any unsettled transactions related to the user's current subscription — such as fees and charging sessions — will be set to an amount of 0. This operation is irreversible and cannot run while a subscription payment is in progress.", "tags": [ "action / user" ], "responses": { "202": { "description": "Action accepted" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." } } }, { "path": "/public-api/actions/users/v1.0/{user}/get-total-eligible-coupon-energy", "method": "GET", "operationId": "userGetTotalEligibleCouponEnergy", "summary": "User / Get total eligible coupon energy", "description": "Returns the total remaining energy (in watt-hours) and coupon count from the user's energy coupons that are eligible for use at a specific EVSE. A coupon is considered eligible when it is active, has remaining energy, is within its validity period, and satisfies all restrictions configured on the coupon — including EVSE type (AC/DC), country allowance, partner allowance, and home charge point restrictions. Use this endpoint to check how much coupon-based energy a user can consume before starting a charging session at a given EVSE.", "tags": [ "action / user" ], "parameters": { "query": { "evseId": { "description": "The ID of the EVSE to check eligibility for", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/users/v1.0/{user}/subscribe-to-plan", "method": "POST", "operationId": "userSubscribeToPlan", "summary": "User / Subscribe to plan", "description": "Subscribe a user to a plan and collect payment. The subscription and installment are created immediately. Payment collection happens asynchronously and does not affect the response. If `paymentMethodId` is provided, that payment method is used exclusively. If omitted, the system uses automatic payment method resolution. For free pre-paid plans (price = 0) and post-paid plans, payment is skipped. If the user already has an active subscription to a different plan, that subscription is cancelled and the new one is activated.", "tags": [ "action / user" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "integer", "description": "The ID of the subscription plan to activate" }, "paymentMethodId": { "type": "integer", "description": "Specific payment method ID to use for collection. Must belong to the target user and be an active tokenized payment method (cards, bank transfers, wallets). If omitted when the plan requires payment at activation, the system uses automatic payment method resolution." }, "reason": { "type": "string", "description": "Free-text reason recorded with the action event for audit purposes." } }, "required": [ "planId", "reason" ] } } } }, "responses": { "202": { "description": "Action accepted." }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/users/v1.0/{user}/subscription-billing-period/{billingPeriod}/retry-payment", "method": "POST", "operationId": "subscriptionBillingPeriodRetryPayment", "summary": "Subscription billing period / Retry payment", "description": "Retry failed payment for a subscription billing period", "tags": [ "action / user" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethodId": { "type": "integer", "description": "ID of a tokenized payment method (type `tokenized`) belonging to the user. If omitted, uses the user's default payment method." } } } } } }, "responses": { "202": { "description": "Payment retry initiated" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "Billing period has no failed payment" }, "422": { "description": "The payload you provided is invalid" }, "423": { "description": "A payment is awaiting 3D Secure confirmation" }, "429": { "description": "A payment is already in progress for this billing period" } } }, { "path": "/public-api/actions/users/v2.0/{user}/export-all-private-data", "method": "GET", "operationId": "userExportAllPrivateData", "summary": "User / Export All Private Data", "description": "Export all private data", "tags": [ "action / user" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/actions/users/v2.0/{user}/redeem-voucher", "method": "POST", "operationId": "userRedeemVoucher", "summary": "User / Redeem Voucher", "description": "Apply a voucher to a user", "tags": [ "action / user" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "The code of the voucher that should be redeemed." } }, "required": [ "code" ] } } } }, "responses": { "202": { "description": "Action accepted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "Action rejected" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/logs/communication/v1.0", "method": "GET", "operationId": "communicationLogsListing", "summary": "Communication logs / Listing", "description": "Get all communication logs with optional filtering and pagination. Returns raw communication payloads including request/response data. For optimal performance, always specify `filter[createdAfter]` and `filter[createdBefore]` to limit the time range.", "tags": [ "logs / communication" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "sessionId": { "type": "integer", "description": "Filter by specific session ID. Takes precedence over evseId, chargePointId, and locationId filters." }, "evseId": { "type": "integer", "description": "Filter by specific EVSE ID. Takes precedence over chargePointId and locationId filters. Ignored when sessionId is provided." }, "chargePointId": { "type": "integer", "description": "Filter by specific charge point ID. Takes precedence over locationId filter. Ignored when sessionId or evseId is provided." }, "locationId": { "type": "integer", "description": "Filter by specific location ID. Returns logs from charge points assigned to the location. Ignored when sessionId, evseId, or chargePointId is provided." }, "direction": { "type": "string", "enum": [ "in", "out" ], "example": "in", "description": "Direction of the communication: - **in**: Message received from charge point - **out**: Message sent to charge point" }, "command": { "type": "array", "items": { "type": "string" }, "description": "Filter by specific command names (e.g., [\"Authorize\", \"StartTransaction\"])" }, "partnerId": { "type": "integer", "description": "Filter by the ID of the partner that owns the charge point." }, "createdAfter": { "type": "string", "format": "date-time", "description": "Return logs created after this timestamp (ISO 8601 format). If omitted, `filter[createdAfter]` defaults to 30 days before the value of `filter[createdBefore]`." }, "createdBefore": { "type": "string", "format": "date-time", "description": "Return logs created before this timestamp (ISO 8601 format) Defaults to the current time if not provided. If omitted and `filter[createdAfter]` is provided, `filter[createdBefore]` defaults to 30 days after the value of `filter[createdAfter]`." } }, "description": "Filters for communication logs listing. For optimal performance, use createdAfter/createdBefore to limit the time range of your queries. If neither `filter[createdAfter]` nor `filter[createdBefore]` is provided, results are limited to logs from the last 30 days relative to the request time. The maximum allowed interval between `filter[createdAfter]` and `filter[createdBefore]` is 30 days. **Filter Precedence:** When multiple entity filters are provided, more specific filters take precedence over less specific ones: - If `sessionId` is provided, `evseId`, `chargePointId`, and `locationId` are ignored. - If `evseId` is provided (without `sessionId`), `chargePointId` and `locationId` are ignored. - If `chargePointId` is provided (without `sessionId` or `evseId`), `locationId` is ignored." } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 500, "default": 500 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "424": { "description": "The requested operation cannot be completed because it depends on communication with an external system (e.g., charge point) that is currently disconnected or unreachable" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/logs/communication/v1.0/{id}", "method": "GET", "operationId": "communicationLogRead", "summary": "Communication log / Read", "description": "Get a single communication log entry by ID.", "tags": [ "logs / communication" ], "parameters": { "path": { "id": { "description": "The communication log entry ID", "type": "string", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/logs/ocpi/v1.0", "method": "GET", "operationId": "listOcpiLogs", "summary": "OCPI Logs / Listing", "description": "Get paginated list of OCPI communication logs with optional filtering and pagination. Returns raw OCPI communication payloads including request/response data. For optimal performance, always specify `filter[createdAfter]` and `filter[createdBefore]` to limit the time range. The maximum allowed date range is 30 days. If no date range is specified, the last 30 days will be returned.", "tags": [ "logs / ocpi" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "roamingConnectionId": { "type": "integer", "description": "Filter by specific roaming connection ID" }, "sessionId": { "type": "integer", "description": "Filter by internal system charging session ID. Returns only log entries tied to the given session (e.g., session operations, CDR operations, start/stop commands). See sessionId in the response for details." }, "evseId": { "type": "integer", "description": "Filter by internal system EVSE ID. Returns only log entries tied to the given EVSE (e.g., session and CDR operations, EVSE/connector location operations, commands). See evseId in the response for details. Ignored when sessionId is provided." }, "locationId": { "type": "integer", "description": "Filter by internal system location ID. Returns only log entries tied to the given location (e.g., session and CDR operations, location operations, commands). See locationId in the response for details. Ignored when sessionId or evseId is provided." }, "direction": { "type": "string", "enum": [ "in", "out" ], "example": "out", "description": "Direction of the OCPI communication: - **in**: Request received from roaming partner - **out**: Request sent to roaming partner" }, "module": { "type": "array", "items": { "type": "string", "enum": [ "locations", "sessions", "cdrs", "tariffs", "tokens", "commands", "versions", "credentials", "hubclient", "chargingpreferences", "smartcharging", "payments" ], "example": "locations", "description": "OCPI module name: - **locations**: Location/EVSE data sync - **sessions**: Charging session data - **cdrs**: Charge Detail Records - **tariffs**: Pricing information - **tokens**: Authorization tokens - **commands**: Remote commands (start/stop/unlock) - **versions**: OCPI version negotiation - **credentials**: Authentication credentials - **hubclient**: Hub client communication - **chargingpreferences**: Smart charging preferences - **smartcharging**: Smart charging profiles - **payments**: Payment processing" }, "description": "Filter by OCPI module names" }, "method": { "type": "array", "items": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH" ], "example": "GET", "description": "HTTP method used for the request" }, "description": "Filter by HTTP methods" }, "createdAfter": { "type": "string", "format": "date-time", "description": "Return logs created after this timestamp (ISO 8601 format). If omitted, `filter[createdAfter]` defaults to 30 days before the value of `filter[createdBefore]`." }, "createdBefore": { "type": "string", "format": "date-time", "description": "Return logs created before this timestamp (ISO 8601 format) Defaults to the current time if not provided. If omitted and `filter[createdAfter]` is provided, `filter[createdBefore]` defaults to 30 days after the value of `filter[createdAfter]`." } }, "description": "Filters for OCPI logs listing. For optimal performance, use createdAfter/createdBefore to limit the time range of your queries. If neither `filter[createdAfter]` nor `filter[createdBefore]` is provided, results are limited to logs from the last 30 days relative to the request time. The maximum allowed interval between `filter[createdAfter]` and `filter[createdBefore]` is 30 days. **Filter Precedence:** When multiple entity filters are provided, more specific filters take precedence: - If `sessionId` is provided, `evseId` and `locationId` filters are ignored - If `evseId` is provided (without `sessionId`), `locationId` filter is ignored" } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 500, "default": 500 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "List of OCPI logs returned successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/logs/ocpi/v1.0/{id}", "method": "GET", "operationId": "readOcpiLog", "summary": "OCPI Log / Read", "description": "Get a single OCPI log entry by ID.", "tags": [ "logs / ocpi" ], "parameters": { "path": { "id": { "description": "The OCPI log entry ID", "type": "string", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/notifications/v1.0", "method": "GET", "operationId": "notificationsListingDeprecated", "summary": "Notifications / Listing", "deprecated": true, "tags": [ "notifications" ], "parameters": { "query": { "per_page": { "description": "The numbers of items to return", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/notifications/v1.0", "method": "POST", "operationId": "notificationsSubscribeDeprecated", "summary": "Notifications / Subscribe", "description": "Subscribe for a webhook. Each notification sent to the webhook will be retried a number of times and will be rate limited. The rate limits, retries and retry intervals will be configured by the platform administrator. Each notification callback will contain a signature in the `X-Signature` request header which can be verified using SHA256-HMAC on the body of the request using the access token that was used when creating the notification as key.", "deprecated": true, "tags": [ "notifications" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "string", "enum": [ "AuthorizationNotification", "authorization.changed", "BootNotification", "ChargePointChangedNotification", "chargePoint.changed", "evse.changed", "ChargePointSyncConfigurationNotification", "CircuitConsumptionNotification", "circuit.changed", "DiagnosticsStatusNotification", "FirmwareStatusNotification", "HardwareStatusNotification", "LocationChangedNotification", "NetworkStatusNotification", "SecurityEventNotification", "SessionMeterValuesNotification", "SessionStartStopNotification", "session.start.stop.notification", "SessionUpdateNotification", "session.chargingPeriod.changed", "UserChangedNotification", "SubOperatorChangedNotification", "TariffChangedNotification", "tariffGroup.changed", "user.subscriptionChanged", "user.subscription.changed", "ReservationChangedNotification", "PaymentMethodChangedNotification", "PartnerInviteChangedNotification", "reservation.changed", "user.paymentMethod.changed", "userBalance.changed", "partnerInvite.changed", "partnerInviteCorporateBillingPolicy.changed", "roamingPlatform.changed", "parkingSpace.occupancyStatus.changed", "partner.changed", "transaction.changed", "settlementReport.created", "idTag.changed", "issue.changed", "chargePoint.dataTransferReceived", "subscriptionPlan.changed", "user.invoiceDetails.changed", "cdr.received", "chargingProfile.applied", "installerJob.changed", "corporateBilling.limitReached" ] } }, "callbackUrl": { "type": "string", "format": "uri", "maxLength": 500, "example": "https://myserver.com/send/callback/here" } }, "required": [ "callbackUrl", "notifications" ] } } } }, "responses": { "201": { "description": "Webhook created" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/notifications/v1.0/{notification}", "method": "GET", "operationId": "notificationsReadDeprecated", "summary": "Notifications / Read", "description": "Get a notification", "deprecated": true, "tags": [ "notifications" ], "responses": { "200": { "description": "Get a notification" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/notifications/v1.0/{notification}", "method": "PUT", "operationId": "notificationsUpdateDeprecated", "summary": "Notifications / Update", "description": "Update a notification", "deprecated": true, "tags": [ "notifications" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "string", "enum": [ "AuthorizationNotification", "authorization.changed", "BootNotification", "ChargePointChangedNotification", "chargePoint.changed", "evse.changed", "ChargePointSyncConfigurationNotification", "CircuitConsumptionNotification", "circuit.changed", "DiagnosticsStatusNotification", "FirmwareStatusNotification", "HardwareStatusNotification", "LocationChangedNotification", "NetworkStatusNotification", "SecurityEventNotification", "SessionMeterValuesNotification", "SessionStartStopNotification", "session.start.stop.notification", "SessionUpdateNotification", "session.chargingPeriod.changed", "UserChangedNotification", "SubOperatorChangedNotification", "TariffChangedNotification", "tariffGroup.changed", "user.subscriptionChanged", "user.subscription.changed", "ReservationChangedNotification", "PaymentMethodChangedNotification", "PartnerInviteChangedNotification", "reservation.changed", "user.paymentMethod.changed", "userBalance.changed", "partnerInvite.changed", "partnerInviteCorporateBillingPolicy.changed", "roamingPlatform.changed", "parkingSpace.occupancyStatus.changed", "partner.changed", "transaction.changed", "settlementReport.created", "idTag.changed", "issue.changed", "chargePoint.dataTransferReceived", "subscriptionPlan.changed", "user.invoiceDetails.changed", "cdr.received", "chargingProfile.applied", "installerJob.changed", "corporateBilling.limitReached" ] } }, "callbackUrl": { "type": "string", "format": "uri", "maxLength": 500, "example": "https://myserver.com/send/callback/here" } }, "required": [ "callbackUrl", "notifications" ] } } } }, "responses": { "200": { "description": "Update a notification" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/notifications/v1.0/{notification}", "method": "DELETE", "operationId": "notificationsUnsubscribeDeprecated", "summary": "Notifications / Unsubscribe", "description": "Unsubscribe for a webhook", "deprecated": true, "tags": [ "notifications" ], "responses": { "204": { "description": "Webhook deleted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/notifications/v2.0", "method": "GET", "operationId": "notificationsListing", "summary": "Notifications / Listing", "tags": [ "notifications" ], "parameters": { "query": { "per_page": { "description": "The numbers of items to return", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/notifications/v2.0", "method": "POST", "operationId": "notificationsSubscribe", "summary": "Notifications / Subscribe", "description": "Subscribe for a webhook or kafka events. Each notification sent to the webhook/kafka will be retried a number of times and will be rate limited. The rate limits, retries and retry intervals will be configured by the platform administrator. Each notification callback will contain a signature in the `X-Signature` request header which can be verified using SHA256-HMAC on the body of the request using the access token that was used when creating the notification as key.", "tags": [ "notifications" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number" }, "via": { "type": "string", "enum": [ "webhook", "kafka" ] }, "notifications": { "type": "array", "items": { "type": "string", "enum": [ "AuthorizationNotification", "authorization.changed", "BootNotification", "ChargePointChangedNotification", "chargePoint.changed", "evse.changed", "ChargePointSyncConfigurationNotification", "CircuitConsumptionNotification", "circuit.changed", "DiagnosticsStatusNotification", "FirmwareStatusNotification", "HardwareStatusNotification", "LocationChangedNotification", "NetworkStatusNotification", "SecurityEventNotification", "SessionMeterValuesNotification", "SessionStartStopNotification", "session.start.stop.notification", "SessionUpdateNotification", "session.chargingPeriod.changed", "UserChangedNotification", "SubOperatorChangedNotification", "TariffChangedNotification", "tariffGroup.changed", "user.subscriptionChanged", "user.subscription.changed", "ReservationChangedNotification", "PaymentMethodChangedNotification", "PartnerInviteChangedNotification", "reservation.changed", "user.paymentMethod.changed", "userBalance.changed", "partnerInvite.changed", "partnerInviteCorporateBillingPolicy.changed", "roamingPlatform.changed", "parkingSpace.occupancyStatus.changed", "partner.changed", "transaction.changed", "settlementReport.created", "idTag.changed", "issue.changed", "chargePoint.dataTransferReceived", "subscriptionPlan.changed", "user.invoiceDetails.changed", "cdr.received", "chargingProfile.applied", "installerJob.changed", "corporateBilling.limitReached" ] } }, "includeTimestampInSignature": { "type": "boolean", "default": false, "description": "When true, the notification timestamp will be included in the HMAC signature calculation. The timestamp is added in front of the signed JSON payload delimited by '.' (dot)." }, "skipRoamingInfrastructure": { "type": "boolean", "default": false, "description": "When set to true, notification updates for infrastructure received via roaming are excluded. Affected notification types: ChargePointChangedNotification, chargePoint.changed, evse.changed, and LocationChangedNotification. All other notification types are unaffected." }, "suppressSelfNotifications": { "type": "boolean", "default": false, "description": "When true, this webhook will not send notifications for actions performed via the Public API using the same API token that owns this webhook. Useful when the integration only needs to react to external events." }, "webhook": { "type": "object", "properties": { "callbackUrl": { "type": "string", "format": "uri", "maxLength": 500, "example": "https://myserver.com/send/callback/here" } }, "required": [ "callbackUrl" ], "description": "Webhook configuration. Only present and required in case via = webhook" }, "kafka": { "type": "object", "properties": { "topic": { "type": "string", "example": "my-topic" }, "brokers": { "type": "array", "items": { "type": "string" }, "example": [ "localhost:9092" ] }, "compressionCodec": { "type": "string", "enum": [ "none", "gzip", "snappy", "lz4" ], "default": "gzip" }, "securityProtocol": { "type": "string", "enum": [ "PLAINTEXT", "SASL_SSL" ], "default": "PLAINTEXT" }, "saslMechanism": { "type": "string", "enum": [ "PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512" ], "default": "PLAIN", "nullable": true }, "saslUsername": { "type": "string", "nullable": true }, "saslPassword": { "type": "string", "nullable": true } }, "required": [ "topic", "brokers" ], "description": "Kafka configuration. Only present and required in case via = kafka" } }, "required": [ "id", "notifications", "via" ] } } } }, "responses": { "201": { "description": "Webhook created" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/notifications/v2.0/{notification}", "method": "GET", "operationId": "notificationRead", "summary": "Notification / Read", "description": "Get a notification", "tags": [ "notifications" ], "responses": { "200": { "description": "Get a notification" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/notifications/v2.0/{notification}", "method": "PUT", "operationId": "notificationsCreate", "summary": "Notifications / Update", "description": "Update a notification", "tags": [ "notifications" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number" }, "via": { "type": "string", "enum": [ "webhook", "kafka" ] }, "notifications": { "type": "array", "items": { "type": "string", "enum": [ "AuthorizationNotification", "authorization.changed", "BootNotification", "ChargePointChangedNotification", "chargePoint.changed", "evse.changed", "ChargePointSyncConfigurationNotification", "CircuitConsumptionNotification", "circuit.changed", "DiagnosticsStatusNotification", "FirmwareStatusNotification", "HardwareStatusNotification", "LocationChangedNotification", "NetworkStatusNotification", "SecurityEventNotification", "SessionMeterValuesNotification", "SessionStartStopNotification", "session.start.stop.notification", "SessionUpdateNotification", "session.chargingPeriod.changed", "UserChangedNotification", "SubOperatorChangedNotification", "TariffChangedNotification", "tariffGroup.changed", "user.subscriptionChanged", "user.subscription.changed", "ReservationChangedNotification", "PaymentMethodChangedNotification", "PartnerInviteChangedNotification", "reservation.changed", "user.paymentMethod.changed", "userBalance.changed", "partnerInvite.changed", "partnerInviteCorporateBillingPolicy.changed", "roamingPlatform.changed", "parkingSpace.occupancyStatus.changed", "partner.changed", "transaction.changed", "settlementReport.created", "idTag.changed", "issue.changed", "chargePoint.dataTransferReceived", "subscriptionPlan.changed", "user.invoiceDetails.changed", "cdr.received", "chargingProfile.applied", "installerJob.changed", "corporateBilling.limitReached" ] } }, "includeTimestampInSignature": { "type": "boolean", "default": false, "description": "When true, the notification timestamp will be included in the HMAC signature calculation. The timestamp is added in front of the signed JSON payload delimited by '.' (dot)." }, "skipRoamingInfrastructure": { "type": "boolean", "default": false, "description": "When set to true, notification updates for infrastructure received via roaming are excluded. Affected notification types: ChargePointChangedNotification, chargePoint.changed, evse.changed, and LocationChangedNotification. All other notification types are unaffected." }, "suppressSelfNotifications": { "type": "boolean", "default": false, "description": "When true, this webhook will not send notifications for actions performed via the Public API using the same API token that owns this webhook. Useful when the integration only needs to react to external events." }, "webhook": { "type": "object", "properties": { "callbackUrl": { "type": "string", "format": "uri", "maxLength": 500, "example": "https://myserver.com/send/callback/here" } }, "required": [ "callbackUrl" ], "description": "Webhook configuration. Only present and required in case via = webhook" }, "kafka": { "type": "object", "properties": { "topic": { "type": "string", "example": "my-topic" }, "brokers": { "type": "array", "items": { "type": "string" }, "example": [ "localhost:9092" ] }, "compressionCodec": { "type": "string", "enum": [ "none", "gzip", "snappy", "lz4" ], "default": "gzip" }, "securityProtocol": { "type": "string", "enum": [ "PLAINTEXT", "SASL_SSL" ], "default": "PLAINTEXT" }, "saslMechanism": { "type": "string", "enum": [ "PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512" ], "default": "PLAIN", "nullable": true }, "saslUsername": { "type": "string", "nullable": true }, "saslPassword": { "type": "string", "nullable": true } }, "required": [ "topic", "brokers" ], "description": "Kafka configuration. Only present and required in case via = kafka" } }, "required": [ "id", "notifications", "via" ] } } } }, "responses": { "200": { "description": "Update a notification" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/notifications/v2.0/{notification}", "method": "DELETE", "operationId": "notificationsUnsubscribe", "summary": "Notifications / Unsubscribe", "description": "Unsubscribe for a notification", "tags": [ "notifications" ], "responses": { "204": { "description": "Webhook deleted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/oauth/revoke", "method": "POST", "operationId": "oauthTokenRevoke", "summary": "OAuth token revocation", "description": "Revoke a short-lived bearer access token per RFC 7009 without rotating the underlying client credential. **Client authentication.** Two methods are supported: - **HTTP Basic** (recommended): send `client_id:client_secret` Base64-encoded in the `Authorization: Basic ...` header. - **POST body**: include `client_id` and `client_secret` in the request body alongside `token`. Sending credentials via both methods in the same request is rejected with `invalid_request`. `Authorization: Bearer` is not accepted for this endpoint. **Request format.** Both `application/x-www-form-urlencoded` and `application/json` are accepted.", "tags": [ "oauth" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "token": { "type": "string", "example": "a3f1c0d2b9e4...", "description": "The bearer access token to revoke." }, "client_id": { "type": "string", "example": "42", "description": "The client identifier. Required when client credentials are sent in the request body instead of via HTTP Basic authentication." }, "client_secret": { "type": "string", "example": "s3cr3t-value", "description": "The client secret. Required when client credentials are sent in the request body instead of via HTTP Basic authentication." } }, "required": [ "token" ], "description": "Token revocation request body. Per RFC 7009 Section 2.1, the client authenticates and presents the bearer access token to revoke. The client may authenticate either via HTTP Basic authentication (recommended) or by including `client_id` and `client_secret` in the request body alongside `token`." } }, "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "example": "a3f1c0d2b9e4...", "description": "The bearer access token to revoke." }, "client_id": { "type": "string", "example": "42", "description": "The client identifier. Required when client credentials are sent in the request body instead of via HTTP Basic authentication." }, "client_secret": { "type": "string", "example": "s3cr3t-value", "description": "The client secret. Required when client credentials are sent in the request body instead of via HTTP Basic authentication." } }, "required": [ "token" ], "description": "Token revocation request body. Per RFC 7009 Section 2.1, the client authenticates and presents the bearer access token to revoke. The client may authenticate either via HTTP Basic authentication (recommended) or by including `client_id` and `client_secret` in the request body alongside `token`." } } } }, "responses": { "200": { "description": "Revocation request accepted. The response is identical for existing, expired, already-revoked, unknown, and wrong-owner tokens." }, "400": { "description": "The request is missing the required `token` parameter or is otherwise malformed." }, "401": { "description": "Client authentication failed." }, "404": { "description": "The OAuth token revocation endpoint is not enabled on this tenant." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/oauth/token", "method": "POST", "operationId": "oauthTokenExchange", "summary": "OAuth / Token Exchange", "description": "Exchange long-lived client credentials for a short-lived bearer access token per RFC 6749 Section 4.4 (Client Credentials Grant). **Client authentication.** Two methods are supported (RFC 6749 Section 2.3): - **HTTP Basic** (recommended): send `client_id:client_secret` Base64-encoded in the `Authorization: Basic ...` header. The request body must contain only `grant_type=client_credentials`. - **POST body**: include `client_id` and `client_secret` in the request body alongside `grant_type=client_credentials`. Sending credentials via both methods in the same request is rejected with `invalid_request`. **Request format.** Both `application/x-www-form-urlencoded` and `application/json` are accepted.", "tags": [ "oauth" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "OAuth 2.0 grant type. Per RFC 6749 Section 4.4, only `client_credentials` is supported for machine-to-machine integrations." }, "client_id": { "type": "string", "example": "42", "description": "The client identifier. Required when client credentials are sent in the request body instead of via HTTP Basic authentication." }, "client_secret": { "type": "string", "example": "s3cr3t-value", "description": "The client secret. Required when client credentials are sent in the request body instead of via HTTP Basic authentication." } }, "required": [ "grant_type" ], "description": "Token exchange request body. Per RFC 6749 Section 4.4, the client may authenticate either via HTTP Basic authentication (recommended) or by including `client_id` and `client_secret` in the request body alongside `grant_type`." } }, "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "OAuth 2.0 grant type. Per RFC 6749 Section 4.4, only `client_credentials` is supported for machine-to-machine integrations." }, "client_id": { "type": "string", "example": "42", "description": "The client identifier. Required when client credentials are sent in the request body instead of via HTTP Basic authentication." }, "client_secret": { "type": "string", "example": "s3cr3t-value", "description": "The client secret. Required when client credentials are sent in the request body instead of via HTTP Basic authentication." } }, "required": [ "grant_type" ], "description": "Token exchange request body. Per RFC 6749 Section 4.4, the client may authenticate either via HTTP Basic authentication (recommended) or by including `client_id` and `client_secret` in the request body alongside `grant_type`." } } } }, "responses": { "200": { "description": "Token issued" }, "400": { "description": "The request is missing a required parameter or specifies an unsupported `grant_type`." }, "401": { "description": "Client authentication failed." }, "404": { "description": "The OAuth token exchange endpoint is not enabled on this tenant." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/admins/v1.0", "method": "GET", "operationId": "adminList", "summary": "Admins / Listing", "description": "Get a list of administrators. Returns administrators belonging to the same operator as the API token. Results are paginated using cursor-based pagination.", "tags": [ "resource / admins" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "permissions" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/admins/v1.0/{admin}", "method": "GET", "operationId": "adminRead", "summary": "Admin / Read", "description": "Get administrator details by ID. Returns administrator information including organizational context (if applicable), role, and optionally permissions. **Admin types:** The admin type can be determined by which optional ID field is present: - `partnerId` - Admin belongs to a partner organization - `subOperatorId` - Admin belongs to a sub-operator organization - `installationAndMaintenanceCompanyId` - Admin belongs to an I&M company - None of the above - Operator-level administrator **SSO field:** The `externalSsoId` field is present when the administrator has SSO authentication enabled. **Permissions include:** Use `?include[]=permissions` to include the administrator's permissions in the response.", "tags": [ "resource / admins" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "permissions" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/admins/v1.0/{admin}/permissions", "method": "GET", "operationId": "adminPermissions", "summary": "Admin / Permissions", "description": "Get administrator permissions. Returns a list of permission names assigned to the administrator. This is an alternative to using `?include[]=permissions` on the admin read endpoint.", "tags": [ "resource / admins" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/authorizations/v1.0/{authorization}", "method": "GET", "operationId": "authorizationReadDeprecated", "summary": "Authorization / Read", "deprecated": true, "tags": [ "resource / authorizations" ], "parameters": { "path": { "authorization": { "description": "The authorization ID to fetch", "type": "string", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/authorizations/v2.0", "method": "GET", "operationId": "authorizationsListing", "summary": "Authorizations / Listing", "description": "**Deprecated:** Use v2.1 endpoint instead. This endpoint does not distinguish between RFID and MAC address (Autocharge) authorizations - both return `id_tag` as the method.", "deprecated": true, "tags": [ "resource / authorizations" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the authorizations created after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the authorizations created before this datetime" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the authorizations that were last updated after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the authorizations that were last updated before this datetime" }, "status": { "type": "string", "description": "Lists only authorizations with one of the following statuses: \"accepted\", \"rejected\", \"pending\"" }, "method": { "type": "string", "description": "Lists only authorizations with one of the following methods: \"user_device\", \"id_tag\", \"mac_address\", \"admin\", \"plug_and_charge\", \"roaming\", \"payment_terminal\", \"plug_and_charge_iso15118\"" }, "partnerId": { "type": "integer", "description": "Lists only authorizations of users who are associated to a particular partner" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/authorizations/v2.0/{authorization}", "method": "GET", "operationId": "authorizationRead", "summary": "Authorization / Read", "description": "**Deprecated:** Use v2.1 endpoint instead. This endpoint does not distinguish between RFID and MAC address (Autocharge) authorizations - both return `id_tag` as the method.", "deprecated": true, "tags": [ "resource / authorizations" ], "parameters": { "path": { "authorization": { "description": "The authorization ID to fetch", "type": "string", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/authorizations/v2.1", "method": "GET", "operationId": "authorizationsListingV2_1", "summary": "Authorizations / Listing", "description": "Get all authorizations", "tags": [ "resource / authorizations" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the authorizations created after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the authorizations created before this datetime" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the authorizations that were last updated after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the authorizations that were last updated before this datetime" }, "status": { "type": "string", "description": "Lists only authorizations with one of the following statuses: \"accepted\", \"rejected\", \"pending\"" }, "method": { "type": "string", "description": "Lists only authorizations with one of the following methods: \"user_device\", \"id_tag\", \"mac_address\", \"admin\", \"plug_and_charge\", \"roaming\", \"payment_terminal\", \"plug_and_charge_iso15118\"" }, "partnerId": { "type": "integer", "description": "Lists only authorizations of users who are associated to a particular partner" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/authorizations/v2.1/{authorization}", "method": "GET", "operationId": "authorizationReadV2_1", "summary": "Authorization / Read", "tags": [ "resource / authorizations" ], "parameters": { "path": { "authorization": { "description": "The authorization ID to fetch", "type": "string", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/booking-requests/v1.0", "method": "GET", "operationId": "bookingRequestsListing", "summary": "Booking Requests / Listing", "description": "Get all booking requests", "tags": [ "resource / booking requests" ], "parameters": { "query": { "filter": { "description": "Filter options for booking requests", "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ], "description": "Filter by booking request status" }, "userId": { "type": "integer", "description": "Filter by user ID" }, "locationId": { "type": "integer", "description": "Filter by location ID" }, "startAfter": { "type": "string", "format": "date-time", "description": "Filter requests with start time after this date" }, "startBefore": { "type": "string", "format": "date-time", "description": "Filter requests with start time before this date" }, "endAfter": { "type": "string", "format": "date-time", "description": "Filter requests with end time after this date" }, "endBefore": { "type": "string", "format": "date-time", "description": "Filter requests with end time before this date" }, "createdAfter": { "type": "string", "format": "date-time", "description": "Filter requests that were created after this date" }, "createdBefore": { "type": "string", "format": "date-time", "description": "Filter requests that were created before this date" }, "externalId": { "type": "string", "example": "OCPI-REQ-12345", "description": "Filter by external identifier from roaming partner (e.g., OCPI request_id)" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/booking-requests/v1.0", "method": "POST", "operationId": "bookingRequestCreate", "summary": "Booking Request / Create", "description": "Create a new booking request. If you want to find the available slots for a given location use the Actions / Location / Check Booking Availability", "tags": [ "resource / booking requests" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "description": "System-generated unique identifier" }, "type": { "type": "string", "enum": [ "create" ], "description": "Type of booking request - must be \"create\"" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ], "description": "Status of booking request: - **pending**: Request is awaiting processing - **approved**: Request has been approved - **rejected**: Request has been rejected" }, "rejectionReason": { "type": "string", "description": "Human-readable reason for rejection. Response behavior: Only present when status is \"rejected\". Omitted for \"pending\" and \"approved\" requests." }, "createdAt": { "type": "string", "format": "date-time" }, "lastUpdatedAt": { "type": "string", "format": "date-time" }, "userId": { "type": "integer", "description": "ID of the user for whom the booking is made" }, "locationId": { "type": "integer", "description": "ID of the target location" }, "externalId": { "type": "string", "maxLength": 255, "description": "External identifier from roaming partner (e.g., OCPI request_id). Response behavior: Only present when an external ID was provided. Omitted when not specified." }, "startAt": { "type": "string", "format": "date-time", "description": "Start time of the booking" }, "endAt": { "type": "string", "format": "date-time", "description": "End time of the booking" }, "evseId": { "type": "integer", "description": "Specific EVSE ID to book. Response behavior: Only present when a specific EVSE was requested. Omitted when EVSE selection was based on criteria or left to the system." }, "evseCriteria": { "type": "object", "properties": { "currentType": { "type": "string", "enum": [ "ac", "dc" ], "nullable": true, "description": "Type of current available on the EVSE: - **ac**: Alternating Current (AC) charging - **dc**: Direct Current (DC) fast charging" }, "minPower": { "type": "number", "description": "Minimum power requirement in kW. Omitted in response when not specified." }, "maxPower": { "type": "number", "description": "Maximum power requirement in kW. Omitted in response when not specified." }, "connectorType": { "type": "string", "enum": [ "type1", "type2", "type3", "chademo", "ccs1", "ccs2", "schuko", "nacs", "cee16", "cee32", "j1772", "inductive", "nema-5-20", "type-e-french", "type-g-british", "type-j-swiss", "avcon", "gb-t-ac", "gb-t-dc", "chaoji", "nema-6-30", "nema-6-50", "mcs", "unknown" ], "nullable": true, "description": "Type of connector available on the EVSE: - **type1**: Type 1 connector (SAE J1772 AC) - **type2**: Type 2 connector (IEC 62196-2 AC) - **type3**: Type 3 connector (IEC 62196-2 AC) - **chademo**: CHAdeMO DC fast charging - **ccs1**: Combined Charging System 1 (CCS1/Combo 1) - **ccs2**: Combined Charging System 2 (CCS2/Combo 2) - **schuko**: Standard European household socket - **nacs**: North American Charging Standard (Tesla) - **cee16**: CEE 16A industrial connector - **cee32**: CEE 32A industrial connector - **j1772**: SAE J1772 connector - **inductive**: Inductive/wireless charging - **nema-5-20**: Domestic M NEMA 5-20 Socket - **type-e-french**: French Type E socket - **type-g-british**: British Type G socket - **type-j-swiss**: Swiss Type J socket - **avcon**: AVCON connector (Australian standard) - **gb-t-ac**: GB/T AC connector (Chinese standard) - **gb-t-dc**: GB/T DC connector (Chinese standard) - **chaoji**: ChaoJi (CHAdeMO 3.0) - **nema-6-30**: NEMA 6-30 - **nema-6-50**: NEMA 6-50 - **mcs**: Megawatt Charging System (MCS) - **unknown**: Connector standard supplied by a 2.3.0+ OCPI roaming peer that is not part of the platform's recognised set. The original peer-supplied value is preserved internally and emitted on outbound OCPI flows." } }, "description": "Criteria for automatic EVSE selection based on technical requirements. Ignored when evseId is explicitly provided. Response behavior: Only present when EVSE criteria were specified in the request. Omitted when evseId was provided or no criteria were specified." }, "parkingSpaceCriteria": { "type": "object", "properties": { "vehicleWeightKg": { "type": "integer", "minimum": 1, "description": "Vehicle weight in kilograms. Omitted in response when not specified." }, "vehicleHeightCm": { "type": "integer", "minimum": 1, "description": "Vehicle height in centimeters. Omitted in response when not specified." }, "vehicleLengthCm": { "type": "integer", "minimum": 1, "description": "Vehicle length in centimeters. Omitted in response when not specified." }, "vehicleWidthCm": { "type": "integer", "minimum": 1, "description": "Vehicle width in centimeters. Omitted in response when not specified." }, "vehicleType": { "type": "string", "enum": [ "two_and_three_wheel_vehicles_and_quadricycles", "passenger_vehicles", "passenger_vehicles_with_trailer", "light_duty_vans", "heavy_duty_tractor_units_without_trailer", "heavy_duty_trucks_without_articulation_point", "heavy_duty_trucks_with_trailer_attached", "buses_or_motor_coaches" ], "nullable": true, "description": "Type of vehicle that can use the parking space: - **two_and_three_wheel_vehicles_and_quadricycles**: Motorcycles, scooters, and similar - **passenger_vehicles**: Standard cars - **passenger_vehicles_with_trailer**: Cars with trailers attached - **light_duty_vans**: Small commercial vans - **heavy_duty_tractor_units_without_trailer**: Heavy trucks without trailer - **heavy_duty_trucks_without_articulation_point**: Heavy trucks without articulation - **heavy_duty_trucks_with_trailer_attached**: Heavy trucks with trailer - **buses_or_motor_coaches**: Buses and coaches" }, "driveThroughRequired": { "type": "boolean", "description": "Whether parking space must support drive-through charging. Omitted in response when not specified." }, "refrigerationOutletRequired": { "type": "boolean", "description": "Whether parking space must have refrigeration outlet. Omitted in response when not specified." }, "dangerousGoodsAllowed": { "type": "boolean", "description": "Whether parking space must allow dangerous goods vehicles. Omitted in response when not specified." } }, "description": "Parking space criteria for selecting EVSE with suitable parking. Response behavior: This property is only included in the response when parking criteria were specified in the request. If no criteria were provided, this property is omitted entirely." }, "authorizedTokenIds": { "type": "array", "items": { "type": "integer" }, "description": "Array of OCPI token IDs that are authorized for this booking. Multiple tokens allow flexibility for roaming users who may have multiple valid authentication methods (e.g., RFID card and mobile app token). When omitted, the booking will not have specific token authorization." } }, "required": [ "type", "userId", "locationId", "startAt", "endAt" ], "description": "Base properties for create booking request (shared between input and response)" }, { "type": "object", "properties": { "id": { "type": "integer", "description": "System-generated unique identifier" }, "type": { "type": "string", "enum": [ "update" ], "description": "Type of booking request - must be \"update\"" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ], "description": "Status of booking request: - **pending**: Request is awaiting processing - **approved**: Request has been approved - **rejected**: Request has been rejected" }, "rejectionReason": { "type": "string", "description": "Human-readable reason for rejection. Response behavior: Only present when status is \"rejected\". Omitted for \"pending\" and \"approved\" requests." }, "createdAt": { "type": "string", "format": "date-time" }, "lastUpdatedAt": { "type": "string", "format": "date-time" }, "bookingId": { "type": "integer", "description": "ID of the target booking to update" }, "userId": { "type": "integer", "description": "ID of the user for whom the booking is made" }, "externalId": { "type": "string", "maxLength": 255, "description": "External identifier from roaming partner (e.g., OCPI request_id). Response behavior: Only present when an external ID was provided. Omitted when not specified." }, "startAt": { "type": "string", "format": "date-time", "description": "Updated start time of the booking" }, "endAt": { "type": "string", "format": "date-time", "description": "Updated end time of the booking" }, "authorizedTokenIds": { "type": "array", "items": { "type": "integer" }, "description": "Array of OCPI token IDs that are authorized for this booking. Multiple tokens allow flexibility for roaming users who may have multiple valid authentication methods (e.g., RFID card and mobile app token). When omitted, the booking will not have specific token authorization." } }, "required": [ "type", "bookingId" ], "description": "Base properties for update booking request (shared between input and response)" }, { "type": "object", "properties": { "id": { "type": "integer", "description": "System-generated unique identifier" }, "type": { "type": "string", "enum": [ "cancel" ], "description": "Type of booking request - must be \"cancel\"" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ], "description": "Status of booking request: - **pending**: Request is awaiting processing - **approved**: Request has been approved - **rejected**: Request has been rejected" }, "rejectionReason": { "type": "string", "description": "Human-readable reason for rejection. Response behavior: Only present when status is \"rejected\". Omitted for \"pending\" and \"approved\" requests." }, "createdAt": { "type": "string", "format": "date-time" }, "lastUpdatedAt": { "type": "string", "format": "date-time" }, "bookingId": { "type": "integer", "description": "ID of the target booking to cancel" }, "externalId": { "type": "string", "maxLength": 255, "description": "External identifier from roaming partner (e.g., OCPI request_id). Response behavior: Only present when an external ID was provided. Omitted when not specified." } }, "required": [ "type", "bookingId" ] } ] } } } }, "responses": { "201": { "description": "Booking request created" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/booking-requests/v1.0/{bookingRequest}", "method": "GET", "operationId": "bookingRequestRead", "summary": "Booking Request / Read", "description": "Get information for a booking request by ID", "tags": [ "resource / booking requests" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/bookings/v1.0", "method": "GET", "operationId": "bookingsListing", "summary": "Bookings / Listing", "description": "Get all bookings", "tags": [ "resource / bookings" ], "parameters": { "query": { "filter": { "description": "Filter options for bookings", "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "accepted", "reserved", "completed", "cancelled", "no-show", "failed" ], "description": "Filter by booking status" }, "userId": { "type": "integer", "description": "Filter by user ID" }, "locationId": { "type": "integer", "description": "Filter by location ID" }, "startAfter": { "type": "string", "format": "date-time", "description": "Filter bookings with start time after this date" }, "startBefore": { "type": "string", "format": "date-time", "description": "Filter bookings with start time before this date" }, "endAfter": { "type": "string", "format": "date-time", "description": "Filter bookings with end time after this date" }, "endBefore": { "type": "string", "format": "date-time", "description": "Filter bookings with end time before this date" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/bookings/v1.0/{booking}", "method": "GET", "operationId": "bookingRead", "summary": "Booking / Read", "description": "Get information for a booking by ID", "tags": [ "resource / bookings" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/cdrs/v2.0", "method": "GET", "operationId": "cdrsListing", "summary": "CDRs / Listing", "description": "Get all CDRs", "tags": [ "resource / cdrs" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "startDateTimeFrom": { "type": "string", "format": "date-time", "description": "Filters CDRs by the start time, selecting records with a start time equal to or later than the specified value. The date-time should be formatted according to ISO 8601 standards." }, "startDateTimeTo": { "type": "string", "format": "date-time", "description": "Filters CDRs by the start time, selecting records with a start time equal to or earlier than the specified value. This filter helps in selecting records up to a certain start time. The provided date-time should be in ISO 8601 format." }, "endDateTimeFrom": { "type": "string", "format": "date-time", "description": "This filter retrieves CDRs with an end time equal to or later than the specified value. It helps filter records based on the end of a timeframe, ensuring that only records ending after a certain point are selected. The date-time format should adhere to ISO 8601 standards." }, "endDateTimeTo": { "type": "string", "format": "date-time", "description": "Filters CDRs based on their end time, selecting those with an end time equal to or earlier than the provided value. This filter limits the selection to records that conclude by a certain time. The date-time should be in ISO 8601 format." }, "operatorId": { "type": "string", "format": "integer", "nullable": true, "description": "Only CDRs associated with a specific Roaming Operator/Provider." }, "platformId": { "type": "string", "format": "integer", "description": "Only CDRs linked to a specific Roaming Platform." }, "roamingId": { "type": "string", "description": "Filters CDRs by the unique identifier within the CPO's platform (and sub-operator platforms)." }, "credit": { "type": "string", "format": "boolean", "description": "Only Credit CDRs." }, "isLocal": { "type": "string", "format": "boolean", "description": "If true only CDRs that we issued as CPO will be returned, if false only CDRs that we received as eMSP will be returned." }, "receivedAfter": { "type": "string", "format": "date-time", "description": "Filters CDRs by the time when received from CPOs, selecting records with a received time equal to or later than the specified value. This filter helps in selecting received records from a certain time and works for non local CDRs. The provided date-time should be following the ISO 8601 standard." }, "receivedBefore": { "type": "string", "format": "date-time", "description": "Filters CDRs by the time when received from CPOs, selecting records with a start time equal to or earlier than the specified value. This filter helps in selecting received records up to a certain time and works for non local CDRs. The provided date-time should be following the ISO 8601 standard." }, "sentAfter": { "type": "string", "format": "date-time", "description": "Filters CDRs by the time when sent to EMSP, selecting records with a sent time equal to or later than the specified value. This filter helps in selecting sent records from a certain time and works for local CDRs. The provided date-time should be following the ISO 8601 standard." }, "sentBefore": { "type": "string", "format": "date-time", "description": "Filters CDRs by the time when sent to EMSP, selecting records with a sent time equal to or earlier than the specified value. This filter helps in selecting sent records from a certain time and works for local CDRs. The provided date-time should be following the ISO 8601 standard." }, "deliveryResponse": { "type": "string", "enum": [ "success", "fail" ], "description": "Filters CDRs that were sent to the EMSP based on their delivery status. Use this dropdown filter to retrieve CDRs with one of the following statuses: - `success`: CDRs successfully **accepted** by the EMSP. - `fail`: CDRs that were **rejected** (not accepted) by the EMSP." }, "sessionId": { "type": "string", "format": "integer", "description": "Filter CDRs by internal session ID to retrieve all CDRs linked to a specific session." }, "externalId": { "type": "string", "description": "Lists only CDRs with the specified external ID value." } } } }, "include": { "description": "Include additional information in the response. The following options are available:
- `externalAppData`: Include external application data in the response", "schema": { "type": "array", "items": { "type": "string", "enum": [ "externalAppData" ] } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/cdrs/v2.0/{cdr}", "method": "GET", "operationId": "cdrRead", "summary": "CDR / Read", "description": "Get a CDR", "tags": [ "resource / cdrs" ], "parameters": { "path": { "cdr": { "type": "integer", "required": true } }, "query": { "include": { "description": "Include additional information in the response. The following options are available:
- `externalAppData`: Include external application data in the response", "schema": { "type": "array", "items": { "type": "string", "enum": [ "externalAppData" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-downtime-periods/v1.0", "method": "GET", "operationId": "chargePointDowntimePeriodsListing", "summary": "Charge Point Downtime Periods / Listing", "description": "Get all Charge Point Downtime Periods", "tags": [ "resource / charge point downtime periods" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "evseId": { "type": "integer" }, "chargePointId": { "type": "integer", "description": "Filter the periods in which the evses belong to the charge point" }, "locationId": { "type": "integer" }, "entryMode": { "type": "string", "enum": [ "manual", "automatic" ] }, "type": { "type": "string", "enum": [ "downtime", "exempt" ] }, "startedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Resources with `startedAt >= startedAfter`." }, "stoppedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Resources with `stoppedAt <= stoppedBefore`." }, "durationLessThan": { "type": "integer", "description": "Resources with duration in minutes less than or equal given value." }, "durationGreaterThan": { "type": "integer", "description": "Resources with duration in minutes greater than or equal given value." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the specific resource that was last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the specific resource that was last updated on and before this datetime" } } } }, "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "statusLog" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-downtime-periods/v1.0", "method": "POST", "operationId": "chargePointDowntimePeriodCreate", "summary": "Charge Point Downtime Period / Create", "description": "Create Manual Exempt Charge Point Downtime Period", "tags": [ "resource / charge point downtime periods" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "chargePointId": { "type": "integer" }, "noticeId": { "type": "integer", "description": "Allowed only notice with `type = exempt`!" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time" } }, "required": [ "chargePointId", "noticeId", "startedAt", "endedAt" ] } } } }, "responses": { "201": { "description": "Charge Point Downtime Period created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-downtime-periods/v1.0/{chargePointDowntimePeriod}", "method": "GET", "operationId": "chargePointDowntimePeriodRead", "summary": "Charge Point Downtime Period / Read", "description": "Get Charge Point Downtime Period", "tags": [ "resource / charge point downtime periods" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "statusLog" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-downtime-periods/v1.0/{chargePointDowntimePeriod}", "method": "DELETE", "operationId": "chargePointDowntimePeriodDelete", "summary": "Charge Point Downtime Period / Delete", "description": "Delete Manual Created Charge Point Downtime Period", "tags": [ "resource / charge point downtime periods" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-downtime-periods/v1.0/{chargePointDowntimePeriod}", "method": "PATCH", "operationId": "chargePointDowntimePeriodUpdate", "summary": "Charge Point Downtime Period / Update", "description": "Update Charge Point Downtime Period", "tags": [ "resource / charge point downtime periods" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "noticeId": { "type": "integer", "nullable": true }, "startedAt": { "type": "string", "format": "date-time", "description": "Allowed only for downtime period with `type = exempt AND entryMode = manual`" }, "endedAt": { "type": "string", "format": "date-time", "description": "Allowed only for downtime period with `type = exempt AND entryMode = manual`" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-downtime-periods/v1.0/{chargePointDowntimePeriod}/status-log", "method": "GET", "operationId": "chargePointDowntimePeriodStatusLog", "summary": "Charge Point Downtime Period / Status Log", "description": "Get the StatusLog entry that triggered this downtime period", "tags": [ "resource / charge point downtime periods" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-models/v1.0", "method": "GET", "operationId": "chargePointModelsListing", "summary": "Charge Point Models / Listing", "description": "Get all Charge Point Models", "tags": [ "resource / charge point models" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "vendorId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-models/v1.0", "method": "POST", "operationId": "chargePointModelCreate", "summary": "Charge Point Model / Create", "description": "Create new Charge Point Model", "tags": [ "resource / charge point models" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "vendorId": { "type": "integer" }, "userManual": { "type": "string", "format": "uri", "description": "A download link for the user manual. Shown in the mobile app for home chargers." }, "installerManual": { "type": "string", "format": "uri", "description": "URL to an externally-hosted installer manual. The system stores this URL reference only (does not download or cache the document) and provides it to installers for viewing/downloading through the installer app interface." } }, "required": [ "name", "vendorId" ] } } } }, "responses": { "201": { "description": "Charge Point Model created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-models/v1.0/{modelId}", "method": "GET", "operationId": "chargePointModelRead", "summary": "Charge Point Model / Read", "description": "Get a Charge Point Model", "tags": [ "resource / charge point models" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-models/v1.0/{modelId}", "method": "DELETE", "operationId": "chargePointModelDelete", "summary": "Charge Point Model / Delete", "description": "Delete a Charge Point Model", "tags": [ "resource / charge point models" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-models/v1.0/{modelId}", "method": "PATCH", "operationId": "chargePointModelUpdate", "summary": "Charge Point Model / Update", "description": "Charge Point Model", "tags": [ "resource / charge point models" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "vendorId": { "type": "integer" }, "userManual": { "type": "string", "format": "uri", "description": "A download link for the user manual. Shown in the mobile app for home chargers." }, "installerManual": { "type": "string", "format": "uri", "description": "URL to an externally-hosted installer manual. The system stores this URL reference only (does not download or cache the document) and provides it to installers for viewing/downloading through the installer app interface." } } } } } }, "responses": { "200": { "description": "Charge Point Model updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-vendors/v1.0", "method": "GET", "operationId": "chargePointVendorsListing", "summary": "Charge Point Vendors / Listing", "description": "Get all Charge Point Vendors", "tags": [ "resource / charge point vendors" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-vendors/v1.0", "method": "POST", "operationId": "chargePointVendorCreate", "summary": "Charge Point Vendor / Create", "description": "Create new Charge Point Vendor", "tags": [ "resource / charge point vendors" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } } }, "responses": { "201": { "description": "Charge Point Vendor created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-vendors/v1.0/{vendorId}", "method": "GET", "operationId": "chargePointVendorRead", "summary": "Charge Point Vendor / Read", "description": "Get a Charge Point Vendor", "tags": [ "resource / charge point vendors" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-vendors/v1.0/{vendorId}", "method": "DELETE", "operationId": "chargePointVendorDelete", "summary": "Charge Point Vendor / Delete", "description": "Delete a Charge Point Vendor", "tags": [ "resource / charge point vendors" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-point-vendors/v1.0/{vendorId}", "method": "PATCH", "operationId": "chargePointVendorUpdate", "summary": "Charge Point Vendor / Update", "description": "Charge Point Vendor", "tags": [ "resource / charge point vendors" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Charge Point Vendor updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v1.0", "method": "GET", "operationId": "chargePointsListingDeprecated", "summary": "Charge Points / Listing", "description": "Get all charge points", "deprecated": true, "tags": [ "resource / charge points" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "desiredSecurityProfileStatus": { "type": "string", "enum": [ "applied", "pending", "rejected" ], "description": "The value of the desiredSecurityProfileStatus by which to filter" }, "evseId": { "type": "string", "format": "integer", "description": "Only list charge point on a certain EVSE" }, "evsePhysicalReference": { "type": "string", "description": "Only list charge point on a certain EVSE, identified by the physicalReference" }, "physicalReference": { "type": "string", "description": "Only list charge point, identified by id" }, "chargePointNetworkId": { "type": "string", "description": "Only list charge point, identified by the NetworkId" }, "chargePointBootNotificationSerialNumber": { "type": "string", "description": "Only list charge points with last boot notification that had this charge_point_serial_number" }, "userId": { "type": "string", "format": "integer", "description": "Only list charge points owned by a certain user" }, "partnerId": { "type": "string", "format": "integer", "description": "Only list charge points owned by a certain partner" }, "accessType": { "type": "string", "enum": [ "public", "private", "personal" ], "description": "Only list charge points with this access type" }, "subOperatorId": { "type": "string", "format": "integer", "description": "Only list charge point for a given subOperator" }, "roaming": { "type": "string", "format": "boolean", "description": "When true - returns only roaming charge points. When false - returns only local charge points." }, "name": { "type": "string", "description": "Exact charge point name" }, "locationId": { "type": "string", "format": "integer", "description": "Only list charge points assigned to the location" }, "managedByOperator": { "type": "string", "format": "boolean", "description": "Only list charge points that are managed by operator or not" }, "externalId": { "type": "string", "description": "Only list charge point, identified by the External ID of the charge point" }, "evseExternalId": { "type": "string", "description": "Only list charge point, identified by the External ID of the EVSE" }, "tag": { "type": "string", "description": "Only list charge points that have the specific tag assigned." } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v1.0", "method": "POST", "operationId": "chargePointCreateDeprecated", "summary": "Charge Point / Create", "description": "Create new charge point", "deprecated": true, "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "networkId": { "type": "string", "nullable": true, "description": "OCPP Identifier" }, "networkProtocol": { "type": "string", "enum": [ "ocpp 1.5", "ocpp 1.6", "ocpp 1.6 soap", "ocpp 2.0.1" ] }, "networkPassword": { "type": "string", "nullable": true }, "networkIp": { "type": "string", "nullable": true, "description": "required for ocpp 1.5 (SOAP)" }, "networkPort": { "type": "string", "nullable": true, "description": "required for ocpp 1.5 (SOAP)" }, "status": { "type": "string", "enum": [ "active", "disabled", "out of order", "demo" ] }, "plugAndCharge": { "type": "boolean", "description": "Enable this flag if you the CP is configured in plug and charge mode, it automatically starts a session when a car is plugged in, and the ID tag should not be authorized. Cannot be enabled on personal charge points when the operator has \"Enforce authentication on home chargers\" enabled in its Home charging settings." }, "locationId": { "type": "integer", "nullable": true, "description": "locationId is always a REQUIRED field for commercial public and commercial private charge points. It is NOT a required field only for personal charge points." }, "pin": { "type": "string", "description": "pin is always a REQUIRED field for personal charge points. It is NOT a required field for commercial public and commercial private charge points." }, "accessType": { "type": "string", "enum": [ "private", "public", "personal" ], "default": "public" }, "desiredSecurityProfile": { "type": "integer", "minimum": 0, "maximum": 2, "nullable": true, "description": "The security profile that the backend will try to force the charge point to use for connecting to the backend. Description of the supported security profiles can be found in the security whitepaper available here - https://www.openchargealliance.org/protocols/ocpp-16/" }, "ownerPartnerId": { "type": "integer", "nullable": true }, "ownerPartnerContractId": { "type": "integer", "nullable": true }, "partnerCorporateBillingAsDefault": { "type": "boolean", "description": "For users who have corporate billing with the same Partner as the Partner assigned to the charge point, the default payment method on this charge point will be the respective corporate billing account of the Partner." }, "partnerAccessType": { "type": "string", "enum": [ "privateViewPrivateUse", "privateViewPublicUse", "publicViewPrivateUse" ], "description": "Applicable only to Commercial Private charge points. Further defines the access type and visibility of the charge point." }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "REMOTE_START_STOP_CAPABLE", "METER_VALUES", "STOP_TRANSACTION_ON_EV_DISCONNECT" ] } }, "managedByOperator": { "type": "boolean" }, "uptimeTrackingEnabled": { "type": "boolean", "default": false, "description": "When set to true, enables Uptime tracking for the charge point by creating an operational period. When set to false or omitted, Uptime tracking remains disabled. **Requirements:** - Charge point must be commercial type (public or private) - Operator must have operational availability enabled **Validation Errors:** - Returns HTTP 422 if charge point is personal type - Returns HTTP 422 if operator has operational availability disabled **Examples:** ```json { \"name\": \"CP-001\", \"accessType\": \"public\", \"uptimeTrackingEnabled\": true } ``` **Validation Error Examples:** Personal charge point error: ```json { \"message\": \"The given data was invalid.\", \"errors\": { \"uptimeTrackingEnabled\": [ \"Uptime tracking can only be enabled for commercial charge points\" ] } } ``` Operator settings error: ```json { \"message\": \"The given data was invalid.\", \"errors\": { \"uptimeTrackingEnabled\": [ \"Operator must have operational availability enabled to track uptime\" ] } } ```" }, "monitoringEnabled": { "type": "boolean", "default": true, "description": "When enabled, issues are created for hardware faults and connectivity problems, and notifications/webhooks are sent. When disabled, no issues are created and no notifications are sent for this charge point." }, "autoRecoveryEnabled": { "type": "boolean", "default": true, "description": "When enabled, the system automatically attempts to recover the charge point when hardware faults are detected (status requests, soft reboots). When disabled, issues are still created (if monitoring is enabled) but no automated recovery actions are taken." }, "autoFaultRecovery": { "type": "boolean", "description": "**DEPRECATED:** Use `monitoringEnabled` and `autoRecoveryEnabled` instead. This field continues to work for backward compatibility, setting both new fields to the same value when provided. New integrations should use the new fields for independent control over monitoring and auto-recovery." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags can be used for filtering and grouping chargers by tag. When doing a PATCH input all tags that should be associated with the charge point. Omitting a tag would remove it from the charge point." }, "templateId": { "type": "integer" }, "evses": { "type": "object", "additionalProperties": { "type": "object", "properties": { "tariffGroupId": { "type": "integer", "description": "The ID of the tariff group attached to the EVSE. If the EVSE is not roaming and tariffGroupId is not specified, the default (free) tariff will be assigned. For roaming EVSEs the Tariff Group can only be updated if the option for manual management of EVSEs is enabled for the roaming CPO." }, "physicalReference": { "type": "string" }, "maxAmperage": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "disabled", "out of order" ] } }, "description": "An associative array with the EVSE network id being used as a key" } }, "externalId": { "type": "string", "nullable": true, "description": "The field should have unique value" } }, "required": [ "templateId", "name", "networkId", "status" ] }, "examples": { "from template": { "description": "Create CP from template", "value": { "templateId": 12, "name": "Example", "networkId": "123456", "status": "active", "locationId": 1 } } } } } }, "responses": { "201": { "description": "Charge point created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v1.0/{chargePoint}", "method": "GET", "operationId": "chargePointReadDeprecated", "summary": "Charge Point / Read", "description": "Get a charge point", "deprecated": true, "tags": [ "resource / charge points" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v1.0/{chargePoint}", "method": "DELETE", "operationId": "chargePointDeleteDeprecated", "summary": "Charge Point / Delete", "description": "Delete a charge point", "deprecated": true, "tags": [ "resource / charge points" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v1.0/{chargePoint}", "method": "PATCH", "operationId": "chargePointUpdateDeprecated", "summary": "Charge Point / Update", "description": "Update a charge point", "deprecated": true, "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "networkId": { "type": "string", "nullable": true, "description": "OCPP Identifier" }, "networkProtocol": { "type": "string", "enum": [ "ocpp 1.5", "ocpp 1.6", "ocpp 1.6 soap", "ocpp 2.0.1" ] }, "networkPassword": { "type": "string", "nullable": true }, "networkIp": { "type": "string", "nullable": true, "description": "required for ocpp 1.5 (SOAP)" }, "networkPort": { "type": "string", "nullable": true, "description": "required for ocpp 1.5 (SOAP)" }, "status": { "type": "string", "enum": [ "active", "disabled", "out of order", "demo" ] }, "plugAndCharge": { "type": "boolean", "description": "Enable this flag if you the CP is configured in plug and charge mode, it automatically starts a session when a car is plugged in, and the ID tag should not be authorized. Cannot be enabled on personal charge points when the operator has \"Enforce authentication on home chargers\" enabled in its Home charging settings." }, "locationId": { "type": "integer", "nullable": true, "description": "locationId is always a REQUIRED field for commercial public and commercial private charge points. It is NOT a required field only for personal charge points." }, "pin": { "type": "string", "description": "pin is always a REQUIRED field for personal charge points. It is NOT a required field for commercial public and commercial private charge points." }, "accessType": { "type": "string", "enum": [ "private", "public", "personal" ], "default": "public" }, "desiredSecurityProfile": { "type": "integer", "minimum": 0, "maximum": 2, "nullable": true, "description": "The security profile that the backend will try to force the charge point to use for connecting to the backend. Description of the supported security profiles can be found in the security whitepaper available here - https://www.openchargealliance.org/protocols/ocpp-16/" }, "ownerPartnerId": { "type": "integer", "nullable": true }, "ownerPartnerContractId": { "type": "integer", "nullable": true }, "partnerCorporateBillingAsDefault": { "type": "boolean", "description": "For users who have corporate billing with the same Partner as the Partner assigned to the charge point, the default payment method on this charge point will be the respective corporate billing account of the Partner." }, "partnerAccessType": { "type": "string", "enum": [ "privateViewPrivateUse", "privateViewPublicUse", "publicViewPrivateUse" ], "description": "Applicable only to Commercial Private charge points. Further defines the access type and visibility of the charge point." }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "REMOTE_START_STOP_CAPABLE", "METER_VALUES", "STOP_TRANSACTION_ON_EV_DISCONNECT" ] } }, "managedByOperator": { "type": "boolean" }, "uptimeTrackingEnabled": { "type": "boolean", "default": false, "description": "When set to true, enables Uptime tracking for the charge point by creating an operational period. When set to false or omitted, Uptime tracking remains disabled. **Requirements:** - Charge point must be commercial type (public or private) - Operator must have operational availability enabled **Validation Errors:** - Returns HTTP 422 if charge point is personal type - Returns HTTP 422 if operator has operational availability disabled **Examples:** ```json { \"name\": \"CP-001\", \"accessType\": \"public\", \"uptimeTrackingEnabled\": true } ``` **Validation Error Examples:** Personal charge point error: ```json { \"message\": \"The given data was invalid.\", \"errors\": { \"uptimeTrackingEnabled\": [ \"Uptime tracking can only be enabled for commercial charge points\" ] } } ``` Operator settings error: ```json { \"message\": \"The given data was invalid.\", \"errors\": { \"uptimeTrackingEnabled\": [ \"Operator must have operational availability enabled to track uptime\" ] } } ```" }, "monitoringEnabled": { "type": "boolean", "default": true, "description": "When enabled, issues are created for hardware faults and connectivity problems, and notifications/webhooks are sent. When disabled, no issues are created and no notifications are sent for this charge point." }, "autoRecoveryEnabled": { "type": "boolean", "default": true, "description": "When enabled, the system automatically attempts to recover the charge point when hardware faults are detected (status requests, soft reboots). When disabled, issues are still created (if monitoring is enabled) but no automated recovery actions are taken." }, "autoFaultRecovery": { "type": "boolean", "description": "**DEPRECATED:** Use `monitoringEnabled` and `autoRecoveryEnabled` instead. This field continues to work for backward compatibility, setting both new fields to the same value when provided. New integrations should use the new fields for independent control over monitoring and auto-recovery." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags can be used for filtering and grouping chargers by tag. When doing a PATCH input all tags that should be associated with the charge point. Omitting a tag would remove it from the charge point." }, "evses": { "type": "object", "additionalProperties": { "type": "object", "properties": { "tariffGroupId": { "type": "integer", "description": "The ID of the tariff group attached to the EVSE. If the EVSE is not roaming and tariffGroupId is not specified, the default (free) tariff will be assigned. For roaming EVSEs the Tariff Group can only be updated if the option for manual management of EVSEs is enabled for the roaming CPO." }, "physicalReference": { "type": "string" }, "maxAmperage": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "disabled", "out of order" ] } }, "description": "An associative array with the EVSE network id being used as a key" } }, "externalId": { "type": "string", "nullable": true, "description": "The field should have unique value" } } } } } }, "responses": { "200": { "description": "Charge point updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v1.0/{chargePoint}/configurations", "method": "GET", "operationId": "chargePointConfigurationsListingDeprecated", "summary": "Charge Point / Configurations / Listing", "description": "Get a charge point's all cached configurations", "deprecated": true, "tags": [ "resource / charge points" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v1.0/{chargePoint}/configurations/{key}", "method": "GET", "operationId": "chargePointConfigurationReadDeprecated", "summary": "Charge Point / Configuration / Read", "description": "Get a charge point's cached configuration for a single key", "deprecated": true, "tags": [ "resource / charge points" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v1.0/{chargePoint}/configurations/{key}", "method": "PATCH", "operationId": "chargePointConfigurationUpdateDeprecated", "summary": "Charge Point / Configuration / Update", "description": "Update a charge point's configuration. The configuration is applied directly to the charge point and you will get response code 406 in case the application fails", "deprecated": true, "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "406": { "description": "The charge point rejected the setting or is not connected right now" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v1.0/{chargePoint}/status", "method": "GET", "operationId": "chargePointStatusRead", "summary": "Charge Point / Status / Read", "description": "Get a charge point's status", "tags": [ "resource / charge points" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0", "method": "GET", "operationId": "chargePointsListing", "summary": "Charge Points / Listing", "description": "Get all charge points", "tags": [ "resource / charge points" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "desiredSecurityProfileStatus": { "type": "string", "enum": [ "applied", "pending", "rejected" ], "description": "The value of the desiredSecurityProfileStatus by which to filter" }, "evsePhysicalReference": { "type": "string", "description": "Only list charge point, identified by evse identifier" }, "networkId": { "type": "string", "description": "Only list charge point, identified by the NetworkId" }, "bootNotificationSerialNumber": { "type": "string", "description": "Only list charge points with last boot notification that had this charge_point_serial_number" }, "modelId": { "type": "string", "description": "Only list charge points, identified by modelId" }, "vendorId": { "type": "string", "description": "Only list charge points, identified by vendorId" }, "userId": { "type": "string", "description": "Only list charge points owned by a certain user" }, "partnerId": { "type": "string", "description": "Only list charge points owned by a certain partner" }, "partnerContractId": { "type": "integer", "description": "Only list charge points associated with a certain partner contract" }, "type": { "type": "string", "enum": [ "public", "private", "personal" ], "description": "Only list charge points with this access type" }, "subOperatorId": { "type": "string", "description": "Only list charge point for a given subOperator" }, "roaming": { "type": "string", "description": "When true - returns only roaming charge points. When false - returns only local charge points." }, "roamingOperatorIds": { "type": "array", "items": { "type": "integer" }, "description": "Filter charge points by one or more roaming operator IDs. Returns charge points that belong to any of the specified roaming operators." }, "name": { "type": "string", "description": "Exact charge point name" }, "locationId": { "type": "string", "description": "Only list charge points assigned to the location" }, "circuitId": { "type": "integer", "description": "Only list charge points added to a certain DLM Circuit" }, "chargingZoneId": { "type": "string", "description": "Only list charge point for a given Charging Zone" }, "managedByOperator": { "type": "string", "description": "Only list charge points that are managed by operator or not" }, "externalId": { "type": "string", "description": "Only list charge point, identified by the External ID of the charge point" }, "utilityId": { "type": "integer" }, "tag": { "type": "string", "description": "Only list charge points that have the specific tag assigned." }, "sharingCode": { "type": "string", "description": "Only list personal charge point with certain sharing code." }, "countryStationId": { "type": "string", "description": "Only list charge points with this country station ID (exact match)" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only charge points created on and after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only charge points created on and before this datetime" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the specific resource that was last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the specific resource that was last updated on and before this datetime" }, "networkStatus": { "type": "string", "enum": [ "available", "temporarily_unavailable", "long-term_unavailable", "never_connected" ], "description": "Filter by current network status of the charge point" }, "lastNetworkStatusUpdateAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only charge points whose network status was updated on or after this datetime" }, "lastNetworkStatusUpdateBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only charge points whose network status was updated on or before this datetime" } } } }, "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "lastBootNotification", "chargingProfile", "smartCharging", "smartChargingPreferences", "personalSmartChargingPreferences", "availablePersonalSmartChargingModes", "notes" ] } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0", "method": "POST", "operationId": "chargePointCreate", "summary": "Charge Point / Create", "description": "Create new charge point", "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "private", "public", "personal" ], "description": "`public` - a charge point visible on the map to everybody
`private` - by default hidden from the map and for private usage only - company and their employees for example. The visibility of the charge point could be managed in partner object, with the different options for accessType.
`personal` - the charge point could have a single owner only. The owner is set when the user claims the charger or with Actions / Change Owner.
" }, "pin": { "type": "string", "description": "Required for personal charge points. The PIN should be provided in the mobile app when the charge point is claimed by a user. Should contain only numbers." }, "locationId": { "type": "integer", "description": "locationId is always a REQUIRED field for commercial public and commercial private charge points. It is NOT a required field only for personal charge points." }, "chargingZoneId": { "type": "integer", "nullable": true }, "electricityRateId": { "type": "integer", "description": "If there is Electricity rate set to the Charge point the electricity cost for each charging session would be tracked. Dynamic electricity rates could not be selected, only ones created in the resource / electricity-rate." }, "subscription": { "type": "object", "properties": { "required": { "type": "boolean", "description": "Only for personal charge points. Require an active subscription to use the charge point." }, "planIds": { "type": "array", "items": { "type": "integer" }, "description": "Only for personal charge points. List of subscription plans for any of which the user should have an active subscription, to be able to use the charge point." } }, "description": "An active subscription could be required for personal (home) charge points in order to use the charge point." }, "networkType": { "type": "string", "enum": [ "cellular", "ethernet", "wlan" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled", "out of order", "demo" ], "description": "Shows the system status of the Charge Point.
`enabled` - the charge point is fully operative. `disabled` - the charge point would not be shown on the map if it is a commercial public or commercial private with the relevant option for visibility nor could be claimed or found by ID if it is personal (home).
`demo` - acts as a simulator so different setups could be tested.
`out of order` - the charge point is visible and shared with users, but a charging session" }, "managedByOperator": { "type": "boolean", "default": true, "description": "This flag indicates whether the operator can actively manage the charge point. If the flag is set to `false` the charge point can still be shown to users, but they can't request to start a session on it. Deprecated. Please use `communicationMode` instead." }, "externalId": { "type": "string" }, "network": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "OCPP Identifier" }, "protocol": { "type": "string", "enum": [ "ocpp 1.5", "ocpp 1.6", "ocpp 1.6 soap", "ocpp 2.0.1" ] }, "password": { "type": "string" }, "ip": { "type": "string", "description": "Required for ocpp 1.5 (SOAP)" }, "port": { "type": "integer", "description": "Required for ocpp 1.5 (SOAP)" } }, "description": "Required and non-empty for charge points communicating directly over OCPP, which is the default communication mode. The requirement applies when `communicationMode` is `direct_ocpp`, or when `communicationMode` is omitted and `managedByOperator` is omitted or `true`; it does not apply to `none`, `via_ocpp_connected_charge_point`, or `managedByOperator: false` charge points." }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "remote_start_stop_capable", "meter_values", "stop_transaction_on_ev_disconnect", "disregard_the_heartbeats", "display_messages" ] }, "description": "`remote_start_stop_capable` - whether Remote start/stop is possible for the Charge Point
`meter_values` - whether the Charge Point should send meter updates to the system
`stop_transaction_on_ev_disconnect` - for ongoing sessions, when the cable is unplugged this should stop the session and if it is returned back a new session would be created.
`disregard_the_heartbeats` - only for OCPP 1.5 SOAP. Network status by default is updated based on the heartbeat messages. When enabled, the Charge Point would be always treated as available and its network status would not depend on heartbeat messages.
`display_messages` - charger has a display and it is enabled to display messages. This capability is enabled automatically when the charger reports the corresponding configuration key. When creating a charge point, the capability is ignored as it is automatically detected on boot.
" }, "autoStartWithoutAuthorization": { "type": "boolean", "default": false, "description": "When enabled the system would allow charging sessions initiated
locally by the charge point assuming it is setup to work in auto-start /
plug-and-charge mode. It would also automatically start a
session with a remote start command if one is not already started by the charging stations a
few seconds after a Preparing status is detected indicating that a vehicle is connected.
Cannot be set to `true` on `personal` charge points when the operator has \"Enforce authentication on home chargers\" enabled in its Home charging settings; setting it to `false` is always allowed." }, "disableAutoStartEmulation": { "type": "boolean", "default": false, "description": "The Auto-start option above does 2 things: (1) it allows charging
sessions started by the charge point assuming that it may be set up locally
to auto-start charging when a vehicle is connected and (2) if the charging
station doesnt start the session within a few seconds after the vehicles is
connected the system sends a remote start command - which is to emulate auto-start
charging. With this checkbox you can disable the emulation and rely
entirely on the charging station to auto-start the charging.
" }, "security": { "type": "object", "properties": { "desiredProfile": { "type": "integer", "description": "The backend will try to set it 3 times at boot notification. If the charge point does not support it, the backend will use the highest security profile the charge point could use.
The following security profiles are supported:
0: `No Authentication`
1: `Unsecured Trasport with Basic Authentication (Plain-back Authentication)` - It does not include authentication for the CSMS, or measures to set up a secure communication channel. Therefore, it should only be used in trusted networks, for instance in networks where there is a VPN between the CSMS and the Charging Station. For field operation it is highly recommended to use a security profile with TLS.
2: `TLS with Basic Authentication (Encrypted Authentication)` - In the TLS with Basic Authentication profile, the communication channel is secured using Transport Layer Security (TLS). The CSMS authenticates itself using a TLS server certificate. The Charging Stations authenticate themselves using HTTP Basic Authentication.
3: `TLS with client-side certificates profile`
" }, "currentProfile": { "type": "integer", "description": "The security profile that is currenty being used by the charge point. Description of the supported security profiles can be found in the security whitepaper available here - https://www.openchargealliance.org/protocols/ocpp-16/" }, "hardwareEnabledProfile": { "type": "integer", "description": "The maximum security profile that the charge point hardware supports. Description of the supported security profiles can be found in the security whitepaper available here - https://www.openchargealliance.org/protocols/ocpp-16/" }, "desiredProfileStatus": { "type": "string", "enum": [ "applied", "pending", "rejected" ], "description": "Whether the last requested desiredSecurityProfile was successfully applied to the charge point." } }, "required": [ "currentProfile" ], "description": "Required with a non-null `desiredProfile` for direct OCPP charge points (the default mode); use `{\"desiredProfile\": 0}` when no profile is enforced. The requirement applies when `communicationMode` is `direct_ocpp`, or when `communicationMode` is omitted and `managedByOperator` is omitted or `true`." }, "modelId": { "type": "integer", "nullable": true, "description": "The ID of the CP Model, if one is associated with the Charge Point. Can be set to null to remove the current CP Model associated with the Charge Point. Mind that on boot the charger reports the hardware model and it is automatically updated." }, "monitoringEnabled": { "type": "boolean", "default": true, "description": "When enabled, issues are created for hardware faults and connectivity problems, and notifications/webhooks are sent. When disabled, no issues are created and no notifications are sent for this charge point." }, "autoRecoveryEnabled": { "type": "boolean", "default": true, "description": "When enabled, the system automatically attempts to recover the charge point when hardware faults are detected (status requests, soft reboots). When disabled, issues are still created (if monitoring is enabled) but no automated recovery actions are taken." }, "enableAutoFaultRecovery": { "type": "boolean", "default": false, "description": "**DEPRECATED:** This field will be removed in v2.1 (target: Q2 2026). Use `monitoringEnabled` and `autoRecoveryEnabled` instead. **Previous Behavior (Single Toggle):** This field previously controlled both monitoring/notifications AND auto-recovery with a single toggle. Setting it to `true` enabled both behaviors, while `false` disabled both. This forced an \"all-or-nothing\" approach. **New Behavior (Independent Controls):** The new fields provide independent control: - `monitoringEnabled` - Controls issue creation and notifications - `autoRecoveryEnabled` - Controls automated recovery attempts **Current Backward Compatibility:** When provided in a request, this field sets **BOTH** `monitoringEnabled` AND `autoRecoveryEnabled` to the same value for backward compatibility. **Migration Guide - Common Use Cases:** 1. **Receive notifications only (no auto-recovery):** - Set `monitoringEnabled: true`, `autoRecoveryEnabled: false` - Use case: Manual control over recovery, but still get alerts 2. **Auto-recovery only (silent mode):** - Set `monitoringEnabled: false`, `autoRecoveryEnabled: true` - Use case: Auto-fix issues without creating alerts (not recommended - no visibility) 3. **Full automation (current default):** - Set `monitoringEnabled: true`, `autoRecoveryEnabled: true` - Old equivalent: `enableAutoFaultRecovery: true` 4. **Disabled (manual control):** - Set `monitoringEnabled: false`, `autoRecoveryEnabled: false` - Old equivalent: `enableAutoFaultRecovery: false` **Migration Deadline:** Please migrate to the new fields by Q1 2026." }, "user": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true }, "automaticFirmwareUpdatesEnabled": { "type": "boolean", "default": true } }, "description": "Owner information along with owner preferences of the charge point when of type *personal*. If smart charging is enabled, smart charging preferences are also included." }, "partner": { "type": "object", "properties": { "id": { "type": "integer" }, "contractId": { "type": "integer" }, "contactId": { "type": "integer" }, "corporateBillingAsDefault": { "type": "boolean", "default": false, "description": "The partner's corporate billing would be used as a payment method by default, when a user who is invited to use the partner's corporate billing starts a session on the charge point." }, "accessType": { "type": "string", "enum": [ "private_view_private_use", "private_view_public_use", "public_view_private_use" ], "description": "`private_view_private_use` - only users invited by the partner with the option to access private charge points could view this charge point on the map and use it.
`private_view_public_use` - only users invited by the partner with the option to access private charge points can view this charge point on the map but anyone who scans the QR or enters the ID can use it.
`public_view_private_use` - anyone could see the charge point on the map with a notice but only users invited by the partner with the option to access private charge points could use it.`
" }, "notice": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "**Deprecated**: Use top-level `noticeId` and `notice` fields instead. The notice is only available if the charge point is of type `private` and the accessType is `public_view_private_use`." } } }, "utilityId": { "type": "integer", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags can be used for filtering and grouping chargers by tag. When doing a PATCH input all tags that should be associated with the charge point. Omitting a tag would remove it from the charge point." }, "uptimeTrackingEnabled": { "type": "boolean", "default": false, "description": "When set to `true`, enables Uptime tracking for the charge point by creating an operational period. When set to `false` or omitted, Uptime tracking remains disabled. Only applicable to commercial charge points (`public` or `private`) on operators with operational availability enabled. Validation: - Returns HTTP 422 with `\"Uptime tracking can only be enabled for commercial charge points\"` when the charge point is `personal` type - Returns HTTP 422 with `\"Operator must have operational availability enabled to track uptime\"` when the operator has operational availability disabled" }, "sharingCode": { "type": "string" }, "enabledRandomisedDelay": { "type": "boolean", "description": "Applicable for `personal` charge points and `private` charge points with Time of Day schedule. For `public` charge points will be omitted." }, "noticeId": { "type": "integer", "nullable": true, "description": "If both noticeId and partner.notice object are provided in the request the noticeId will be used to complete the request NOT the partner.notice object!" }, "usesRenewableEnergy": { "type": "boolean", "default": false, "description": "When enabled, if no electricity rate is assigned to the charge point any roaming session will be marked as using renewable energy. The actual energy mix can be specified in an electricity rate, which can then be assigned to the charge point. In that case the energy mix will be provided for roaming sessions. This information can be gathered from the utility provider or third-party platforms that provide this information to the public." }, "integratedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 formatted date" }, "manufacturedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 formatted date" }, "ocppConnectedChargePointId": { "type": "integer", "description": "The ID of the charge point that is connected to the backend and used by this charge point for OCPP communication. Required when the `communicationMode` is `via_ocpp_connected_charge_point`." }, "communicationMode": { "type": "string", "enum": [ "none", "direct_ocpp", "via_ocpp_connected_charge_point" ], "description": "This property is required!
It obsoletes the `managedByOperator` property, which can still be used by older implementations, so neither is marked as required.
Indicates how the charge point communicates with the backend.
`none` - the charge point is not connected to the backend. The charge point can be displayed to users with instructions how to use it. An informational notice can be associated with the charge point using the `noticeId` property.
`direct_ocpp` - the charge point is connected through OCPP and is actively being managed by the backend.
`via_ocpp_connected_charge_point` - the charge point is a satellite of another charge point which communicates through OCPP and is identified by `ocppConnectedChargePointId`. The charge point is not actively managed, but inherits most of its properties from its master charge point. When creating this type of charge point, the following fields are not required and will not be used:
- electricityRateId
- networkType
- capabilities
- network
- autoStartWithoutAuthorization
- disableAutoStartEmulation
- security
- modelId
- enableAutoFaultRecovery
- utilityId
- usesRenewableEnergy
- enabledRandomisedDelay
- integratedAt
- manufacturedAt
" }, "electricityCostReimbursementIntegrationId": { "type": "integer", "example": 123, "nullable": true, "description": "The ID of the third-party electricity cost reimbursement integration to use for processing reimbursements for charging sessions at this charge point. Only applicable to personal (home) charge points - ignored for public and private charge points." }, "installationAndMaintenanceCompanyId": { "type": "integer", "example": 456, "nullable": true, "description": "Optional. The ID of the Installation & Maintenance company associated with this charge point. Must be owned by the same operator. Validation: - If provided and not null, must reference a valid I&M company ID that belongs to the operator - Invalid or cross-operator I&M company IDs return validation error: \"The selected installation and maintenance company ID is invalid\" - Can be set to null to remove I&M company assignment" }, "countryStationId": { "type": "string", "maxLength": 255, "example": "BNA0001", "nullable": true, "description": "Country-specific station identifier for NAP reporting (e.g., BNetzA Stations-ID for Germany)." }, "calibrationLawDataAvailability": { "type": "string", "enum": [ "local", "not_available" ], "example": "local", "nullable": true, "description": "Calibration law data availability override for Hubject/OICP compliance. Set to `local` if the charger has a certified on-site display for signed meter readings. Set to `not_available` for chargers whose hardware is not calibration-law compliant (e.g. cannot produce signed meter values). Set to `null` to use automatic resolution (External when Eichrecht is supported, Not Available otherwise)." } }, "required": [ "name", "type", "status" ] } } } }, "responses": { "201": { "description": "Charge point created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}", "method": "GET", "operationId": "chargePointRead", "summary": "Charge Point / Read", "description": "Get a charge point", "tags": [ "resource / charge points" ], "responses": { "200": { "description": "Charge point returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}", "method": "DELETE", "operationId": "chargePointDelete", "summary": "Charge Point / Delete", "description": "Delete a charge point", "tags": [ "resource / charge points" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}", "method": "PATCH", "operationId": "chargePointUpdate", "summary": "Charge Point / Update", "description": "Update a charge point. The update is rejected with 409 while it would leave the charge point in a state its configuration forbids — for example removing the electricity rate while a reimbursement policy that resolves the rate from the charge point is attached. Replacing the electricity rate with another valid rate is allowed.", "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "private", "public", "personal" ], "description": "`public` - a charge point visible on the map to everybody
`private` - by default hidden from the map and for private usage only - company and their employees for example. The visibility of the charge point could be managed in partner object, with the different options for accessType.
`personal` - the charge point could have a single owner only. The owner is set when the user claims the charger or with Actions / Change Owner.
" }, "pin": { "type": "string", "nullable": true, "description": "Required if `accessType` is `personal`. The PIN should be provided in the mobile app when the charge point is claimed by a user. Should contain only numbers." }, "locationId": { "type": "integer", "nullable": true, "description": "Required if `accessType` is `public` or `private`. NOT required if `accessType` is `personal`." }, "chargingZoneId": { "type": "integer", "nullable": true }, "electricityRateId": { "type": "integer", "nullable": true, "description": "If there is Electricity rate set to the Charge point the electricity cost for each charging session would be tracked. Dynamic electricity rates could not be selected, only ones created in the resource / electricity-rate. Set to `null` to clear the reference. Clearing the rate is rejected with HTTP 409 while a reimbursement policy that resolves the rate from the charge point is attached. Replacing it with another valid rate is allowed." }, "electricityCostReimbursementIntegrationId": { "type": "integer", "example": 123, "nullable": true, "description": "The ID of the third-party electricity cost reimbursement integration to use for processing reimbursements for charging sessions at this charge point. Only applicable to personal (home) charge points - ignored for public and private charge points." }, "installationAndMaintenanceCompanyId": { "type": "integer", "example": 456, "nullable": true, "description": "The ID of the Installation & Maintenance company associated with this charge point. Must be owned by the same operator. Validation: - If provided and not null, must reference a valid I&M company ID that belongs to the operator - Invalid or cross-operator I&M company IDs return validation error: \"The selected installation and maintenance company ID is invalid\" - Can be set to null to remove I&M company assignment" }, "countryStationId": { "type": "string", "maxLength": 255, "example": "BNA0001", "nullable": true, "description": "Country-specific station identifier for NAP reporting (e.g., BNetzA Stations-ID for Germany)." }, "calibrationLawDataAvailability": { "type": "string", "enum": [ "local", "not_available" ], "example": "local", "nullable": true, "description": "Calibration law data availability override for Hubject/OICP compliance. Set to `local` if the charger has a certified on-site display for signed meter readings. Set to `not_available` for chargers whose hardware is not calibration-law compliant (e.g. cannot produce signed meter values). Set to `null` to use automatic resolution (External when Eichrecht is supported, Not Available otherwise)." }, "subscription": { "type": "object", "properties": { "required": { "type": "boolean", "description": "Only for personal charge points. Require an active subscription to use the charge point." }, "planIds": { "type": "array", "items": { "type": "integer" }, "description": "Only for personal charge points. List of subscription plans for any of which the user should have an active subscription, to be able to use the charge point." } }, "description": "An active subscription could be required for personal (home) charge points in order to use the charge point." }, "networkType": { "type": "string", "enum": [ "cellular", "ethernet", "wlan" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled", "out of order", "demo" ], "description": "Shows the system status of the Charge Point. * `enabled` - the charge point is fully operative. * `disabled` - the charge point would not be shown on the map if it is a commercial public or commercial private with the relevant option for visibility nor could be claimed or found by ID if it is personal (home).
* `demo` - acts as a simulator so different setups could be tested. * `out of order` - the charge point is visible and shared with users, but a charging session" }, "managedByOperator": { "type": "boolean", "default": true, "description": "This flag indicates whether the operator can actively manage the charge point. If the flag is set to `false` the charge point can still be shown to users, but they can't request to start a session on it. Deprecated. Please use `communicationMode` instead. The `communicationMode` can only be set when creating a charge point." }, "externalId": { "type": "string", "nullable": true }, "network": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "OCPP Identifier" }, "protocol": { "type": "string", "enum": [ "ocpp 1.5", "ocpp 1.6", "ocpp 1.6 soap", "ocpp 2.0.1" ], "nullable": true }, "password": { "type": "string", "nullable": true }, "ip": { "type": "string", "nullable": true, "description": "Required for ocpp 1.5 (SOAP)" }, "port": { "type": "integer", "nullable": true, "description": "Required for ocpp 1.5 (SOAP)" } } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "remote_start_stop_capable", "meter_values", "stop_transaction_on_ev_disconnect", "disregard_the_heartbeats", "display_messages" ] }, "description": "`remote_start_stop_capable` - whether Remote start/stop is possible for the Charge Point
`meter_values` - whether the Charge Point should send meter updates to the system
`stop_transaction_on_ev_disconnect` - for ongoing sessions, when the cable is unplugged this should stop the session and if it is returned back a new session would be created.
`disregard_the_heartbeats` - only for OCPP 1.5 SOAP. Network status by default is updated based on the heartbeat messages. When enabled, the Charge Point would be always treated as available and its network status would not depend on heartbeat messages.
`display_messages` - charger has a display and it is enabled to display messages. This capability is enabled automatically when the charger reports the corresponding configuration key. When creating a charge point, the capability is ignored as it is automatically detected on boot.
" }, "autoStartWithoutAuthorization": { "type": "boolean", "default": false, "description": "When enabled the system would allow charging sessions initiated
locally by the charge point assuming it is setup to work in auto-start /
plug-and-charge mode. It would also automatically start a
session with a remote start command if one is not already started by the charging stations a
few seconds after a Preparing status is detected indicating that a vehicle is connected.
Cannot be set to `true` on `personal` charge points when the operator has \"Enforce authentication on home chargers\" enabled in its Home charging settings; setting it to `false` is always allowed." }, "disableAutoStartEmulation": { "type": "boolean", "default": false, "description": "The Auto-start option above does 2 things: (1) it allows charging
sessions started by the charge point assuming that it may be set up locally
to auto-start charging when a vehicle is connected and (2) if the charging
station doesnt start the session within a few seconds after the vehicles is
connected the system sends a remote start command - which is to emulate auto-start
charging. With this checkbox you can disable the emulation and rely
entirely on the charging station to auto-start the charging.
" }, "security": { "type": "object", "properties": { "desiredProfile": { "type": "integer", "description": "The backend will try to set it 3 times at boot notification. If the charge point does not support it, the backend will use the highest security profile the charge point could use.
The following security profiles are supported:
0: `No Authentication`
1: `Unsecured Trasport with Basic Authentication (Plain-back Authentication)` - It does not include authentication for the CSMS, or measures to set up a secure communication channel. Therefore, it should only be used in trusted networks, for instance in networks where there is a VPN between the CSMS and the Charging Station. For field operation it is highly recommended to use a security profile with TLS.
2: `TLS with Basic Authentication (Encrypted Authentication)` - In the TLS with Basic Authentication profile, the communication channel is secured using Transport Layer Security (TLS). The CSMS authenticates itself using a TLS server certificate. The Charging Stations authenticate themselves using HTTP Basic Authentication.
3: `TLS with client-side certificates profile`
" }, "currentProfile": { "type": "integer", "description": "The security profile that is currenty being used by the charge point. Description of the supported security profiles can be found in the security whitepaper available here - https://www.openchargealliance.org/protocols/ocpp-16/" }, "hardwareEnabledProfile": { "type": "integer", "description": "The maximum security profile that the charge point hardware supports. Description of the supported security profiles can be found in the security whitepaper available here - https://www.openchargealliance.org/protocols/ocpp-16/" }, "desiredProfileStatus": { "type": "string", "enum": [ "applied", "pending", "rejected" ], "description": "Whether the last requested desiredSecurityProfile was successfully applied to the charge point." } } }, "modelId": { "type": "integer", "nullable": true, "description": "The ID of the CP Model, if one is associated with the Charge Point. Can be set to null to remove the current CP Model associated with the Charge Point. Mind that on boot the charger reports the hardware model and it is automatically updated." }, "monitoringEnabled": { "type": "boolean", "default": true, "description": "When enabled, issues are created for hardware faults and connectivity problems, and notifications/webhooks are sent. When disabled, no issues are created and no notifications are sent for this charge point." }, "autoRecoveryEnabled": { "type": "boolean", "default": true, "description": "When enabled, the system automatically attempts to recover the charge point when hardware faults are detected (status requests, soft reboots). When disabled, issues are still created (if monitoring is enabled) but no automated recovery actions are taken." }, "enableAutoFaultRecovery": { "type": "boolean", "default": false, "description": "**DEPRECATED:** This field will be removed in v2.1 (target: Q2 2026). Use `monitoringEnabled` and `autoRecoveryEnabled` instead. **Previous Behavior (Single Toggle):** This field previously controlled both monitoring/notifications AND auto-recovery with a single toggle. Setting it to `true` enabled both behaviors, while `false` disabled both. This forced an \"all-or-nothing\" approach. **New Behavior (Independent Controls):** The new fields provide independent control: - `monitoringEnabled` - Controls issue creation and notifications - `autoRecoveryEnabled` - Controls automated recovery attempts **Current Backward Compatibility:** When provided in a request, this field sets **BOTH** `monitoringEnabled` AND `autoRecoveryEnabled` to the same value for backward compatibility. **Migration Guide - Common Use Cases:** 1. **Receive notifications only (no auto-recovery):** - Set `monitoringEnabled: true`, `autoRecoveryEnabled: false` - Use case: Manual control over recovery, but still get alerts 2. **Auto-recovery only (silent mode):** - Set `monitoringEnabled: false`, `autoRecoveryEnabled: true` - Use case: Auto-fix issues without creating alerts (not recommended - no visibility) 3. **Full automation (current default):** - Set `monitoringEnabled: true`, `autoRecoveryEnabled: true` - Old equivalent: `enableAutoFaultRecovery: true` 4. **Disabled (manual control):** - Set `monitoringEnabled: false`, `autoRecoveryEnabled: false` - Old equivalent: `enableAutoFaultRecovery: false` **Migration Deadline:** Please migrate to the new fields by Q1 2026." }, "user": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true }, "automaticFirmwareUpdatesEnabled": { "type": "boolean", "default": true } }, "description": "Owner information along with owner preferences of the charge point when of type *personal*. If smart charging is enabled, smart charging preferences are also included." }, "partner": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "The ID of the partner to assign to this charge point. When explicitly providing a partner ID (non-null value), a valid `contractId` is required. Set to null to remove the partner assignment." }, "contractId": { "type": "integer", "nullable": true, "description": "The ID of the partner contract. Required when `partner.id` is explicitly provided in the request." }, "contactId": { "type": "integer", "nullable": true, "description": "Deprecated. Use `contractId` instead. Required when `partner.id` is explicitly provided in the request." }, "corporateBillingAsDefault": { "type": "boolean", "default": false, "description": "The partner's corporate billing would be used as a payment method by default, when a user who is invited to use the partner's corporate billing starts a session on the charge point." }, "accessType": { "type": "string", "enum": [ "private_view_private_use", "private_view_public_use", "public_view_private_use" ], "nullable": true, "description": "`private_view_private_use` - only users invited by the partner with the option to access private charge points could view this charge point on the map and use it.
`private_view_public_use` - only users invited by the partner with the option to access private charge points can view this charge point on the map but anyone who scans the QR or enters the ID can use it.
`public_view_private_use` - anyone could see the charge point on the map with a notice but only users invited by the partner with the option to access private charge points could use it.`
" }, "notice": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "nullable": true, "description": "**Deprecated**: Use top-level `noticeId` field instead. Setting notice translations directly is no longer supported. The notice is only available if the charge point is of type `private` and the accessType is `public_view_private_use`." } } }, "utilityId": { "type": "integer", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags can be used for filtering and grouping chargers by tag. When doing a PATCH input all tags that should be associated with the charge point. Omitting a tag would remove it from the charge point." }, "uptimeTrackingEnabled": { "type": "boolean", "description": "Controls Uptime tracking for the charge point. When set to `true`, enables Uptime tracking by creating an operational period. When set to `false`, disables Uptime tracking. When omitted, the current value is preserved. Only applicable to commercial charge points (`public` or `private`) on operators with operational availability enabled. Validation: - Returns HTTP 422 with `\"Uptime tracking can only be enabled for commercial charge points\"` when the charge point is `personal` type - Returns HTTP 422 with `\"Operator must have operational availability enabled to track uptime\"` when the operator has operational availability disabled" }, "enabledRandomisedDelay": { "type": "boolean", "description": "Applicable for `personal` charge points and `private` charge points with Time of Day schedule. For `public` charge points will be omitted." }, "noticeId": { "type": "integer", "nullable": true, "description": "If both noticeId and partner.notice object are provided in the request the noticeId will be used to complete the request NOT the partner.notice object!" }, "usesRenewableEnergy": { "type": "boolean", "default": false, "description": "When enabled, if no electricity rate is assigned to the charge point any roaming session will be marked as using renewable energy. The actual energy mix can be specified in an electricity rate, which can then be assigned to the charge point. In that case the energy mix will be provided for roaming sessions. This information can be gathered from the utility provider or third-party platforms that provide this information to the public." }, "integratedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 formatted date" }, "manufacturedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 formatted date" }, "tariffDisplayMessages": { "type": "object", "properties": { "sendDefaultPrice": { "type": "boolean", "default": true, "description": "Sends default tariff information on boot and when tariffs change." }, "sendUserPrice": { "type": "boolean", "default": true, "description": "Sends the authorized user's tariff at session authorization." }, "sendRunningCost": { "type": "boolean", "default": true, "description": "Sends real-time cost updates during charging sessions." }, "sendFinalCost": { "type": "boolean", "default": true, "description": "Sends the total session cost after charging ends." } }, "description": "Per-message settings for tariff and cost display. Only applicable when the charge point supports tariff and cost display (`displayTariffAndCosts` is `true`). All fields are optional. On create, omitted fields default to `true`. On update, omitted fields retain their current value." }, "publicSharing": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "When `true`, same-operator users without a sharing invite for this charge point can authorise sessions, and the owner is reimbursed by the operator for public-access sessions. Accepted independently of `roamingPublishEnabled`. Preconditions: enabling requires each of (1) a location with country and postal code, (2) the tariff group assigned to the charge point's EVSEs (`tariffGroupId`) contains at least one tariff, and (3) `reimbursementPolicyId` references an active operator-owned reimbursement policy. A request that enables public sharing while any of those three preconditions is missing returns HTTP 422 with a `publicSharing.enabled` error naming each missing precondition." }, "roamingPublishEnabled": { "type": "boolean", "description": "When `true`, the charge point is published to OCPI roaming partners. Accepted independently of `enabled` for a roaming-only configuration. Subject to the same three preconditions as `enabled`." }, "reimbursementPolicyId": { "type": "integer", "nullable": true, "description": "References the reimbursement policy used to reimburse the charge point owner for public-access sessions. Set to `null` to clear the reference. Selecting a policy that resolves the rate from the charge point requires the charge point to have an electricity rate assigned, whether or not the same request enables public sharing; that state conflict returns HTTP 409 rather than a validation error. Replacing the electricity rate with another valid rate is allowed." } }, "description": "Public access controls for a `personal` charge point. Only applicable to `personal` charge points and requires the `home-charging-reimbursement` feature." } } } } } }, "responses": { "200": { "description": "Charge point updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/available-personal-smart-charging-modes", "method": "GET", "operationId": "chargePointAvailablePersonalSmartChargingModesListing", "summary": "Charge Point / Available personal smart charging modes / Listing", "description": "Get all available personal smart charging modes", "tags": [ "resource / charge points" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/configurations", "method": "GET", "operationId": "chargePointConfigurationsListing", "summary": "Charge Point / Configurations / Listing", "description": "Get a charge point's all cached configurations", "tags": [ "resource / charge points" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Only list configuration keys identified by variable name" }, "instance": { "type": "string", "description": "Only list configuration keys identified by instance" }, "componentName": { "type": "string", "description": "Only list configuration keys identified by component name" }, "evseId": { "type": "integer", "description": "Only list configuration keys identified by EVSE ID" }, "componentInstance": { "type": "string", "description": "Only list configuration keys identified by component instance" }, "connectorId": { "type": "integer", "description": "Only list configuration keys identified by connector ID" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/configurations/{key}", "method": "GET", "operationId": "chargePointConfigurationRead", "summary": "Charge Point / Configuration / Read", "description": "Get a charge point's cached configuration for a single key", "tags": [ "resource / charge points" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/configurations/{key}", "method": "PATCH", "operationId": "chargePointConfigurationUpdate", "summary": "Charge Point / Configuration / Update", "description": "Update a charge point's configuration. The configuration is applied directly to the charge point and you will get response code 406 in case the application fails", "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "This field is required when the configuration key is one of the standard OCPP keys, as defined in the OCPP documentation under \"Standard Configuration Key Names & Values\"." } } } } } }, "responses": { "200": { "description": "Updated" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "406": { "description": "The charge point rejected the setting or is not connected right now" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/evses", "method": "GET", "operationId": "chargePointEvsesListing", "summary": "Charge Point / EVSEs / Listing", "description": "Get all EVSEs of the Charge Point", "tags": [ "resource / charge points" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "chargingProfile", "connectors", "notes" ] } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/evses", "method": "POST", "operationId": "chargePointEvseCreate", "summary": "Charge Point / EVSE / Create", "description": "Create new EVSE within the Charge Point", "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "physicalReference": { "type": "string", "description": "The identifier that is presented to the users, so they can identify the EVSE at the location." }, "currentType": { "type": "string", "enum": [ "ac", "dc" ], "description": "Type of current available on the EVSE: - **ac**: Alternating Current (AC) charging - **dc**: Direct Current (DC) fast charging" }, "label": { "type": "string", "description": "The EVSE label will be exposed and visualized in the mobile application" }, "networkId": { "type": "string", "description": "The OCPP evse identifier (should be consecutive numbers starting from 1)" }, "status": { "type": "string", "enum": [ "enabled", "disabled", "out of order" ], "description": "For roaming EVSEs the status can only be updated if the option for manual management of EVSEs is enabled for the roaming CPO." }, "midMeterCertificationEndYear": { "type": "integer", "nullable": true, "description": "The mid meter certification end year." }, "tariffGroupId": { "type": "integer", "nullable": true, "description": "The ID of the tariff group attached to the EVSE. If the EVSE is not roaming and tariffGroupId is not specified, the default (free) tariff will be assigned. For roaming EVSEs the Tariff Group can only be updated if the option for manual management of EVSEs is enabled for the roaming CPO." }, "allowsReservation": { "type": "boolean", "description": "Manages whether reservations are allowed on this EVSE. Requires the Reservations to be activated for the system in order to enable for the EVSE." }, "bookingEnabled": { "type": "boolean", "description": "Indicates if the EVSE can be booked. Requires the Bookings to be activated for the operator and automatically enables allowsReservation when set to true." }, "monitoringEnabled": { "type": "boolean", "description": "When disabled, this EVSE will not be listed or counted in the Faults & connectivity loss widget or lens. The charge point will still appear for charge point-level faults (network loss, hardware faulted). Defaults to true." }, "powerOptions": { "type": "object", "properties": { "maxOutputVoltage": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Maximum output voltage for DC charging." }, "maxPower": { "type": "integer", "nullable": true, "description": "Maximum power of the EVSE in W (Watts)." }, "maxVoltage": { "type": "string", "enum": [ "230", "380", "400", "480", "120", "208", "240", "110-130", "220-240", "277" ], "nullable": true, "description": "The maximum intake (input) voltage of the EVSE. For the ac current type the output voltage is the same as this intake voltage, while for the dc current type the output voltage can differ and is exposed separately in maxOutputVoltage. The maxVoltage of a charge point can fluctuate. Hence, when creating a charge point in the system, the maxVoltage is given as a range. For OCPI purposes it maps as follows: 220-240 = 230 110-130 = 120 400 = 400 380 = 380" }, "maxAmperage": { "type": "number", "nullable": true }, "phases": { "type": "string", "enum": [ "single_phase", "three_phase", "split_phase" ], "nullable": true }, "phaseRotation": { "type": "string", "enum": [ "RST", "RTS", "SRT", "STR", "TRS", "TSR" ], "nullable": true, "description": "`R` stands for `L1`,
`S` - for `L2`
`T` - for `L3`
So for example `RST` = `L1`, `L2`, `L3`, while `RTS` = `L1`, `L3`, `L2`, etc.
We are deriving the connected phase from this property for single phase if connectedPhase is not provided. Please don't rely on this property anymore as this functionality will be turned of in near future. Pass the correct connectedPhase instead. If you pass both properties (connectedPhase and phaseRotation) only connectedPhase will be taken into consideration for determining the phase." }, "connectedPhase": { "type": "string", "enum": [ "L1", "L2", "L3", "L1_L2", "L1_L3", "L2_L3" ], "nullable": true, "description": "Specifies the active line conductors used in the circuit. - `L1_L2` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L2_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L2` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L3` - Valid when `phases` = `single_phase` in electrical configuration `star`" } } }, "externalId": { "type": "string" }, "capabilityOverrides": { "type": "object", "properties": { "rfidReader": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "creditCardPayable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "contactlessCardSupport": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "debitCardPayable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "chipCardSupport": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "pedTerminal": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "remoteStartStop": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "unlockCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "reservable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "chargingProfileCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "chargingPreferencesCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "startSessionConnectorRequired": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "tokenGroupCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" } }, "description": "Manual overrides for individual EVSE capabilities. Each property is independent. Send `force_enable` or `force_disable` to set or replace an override. Send `auto` to clear an existing override (the capability returns to automated detection). Omit a property to leave its current override unchanged." } }, "required": [ "physicalReference", "currentType", "networkId", "status" ] } } } }, "responses": { "201": { "description": "EVSE created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/evses/{evse}", "method": "GET", "operationId": "chargePointEvseRead", "summary": "Charge Point / EVSE / Read", "description": "Get an EVSE from a Charge Point", "tags": [ "resource / charge points" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "chargingProfile", "connectors", "accessibleParkingSpaces" ] } } } } }, "responses": { "200": { "description": "EVSE returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/evses/{evse}", "method": "DELETE", "operationId": "chargePointEvseDelete", "summary": "Charge Point / EVSE / Delete", "description": "Delete an EVSE", "tags": [ "resource / charge points" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/evses/{evse}", "method": "PATCH", "operationId": "chargePointEvseUpdate", "summary": "Charge Point / EVSE / Update", "description": "Update an EVSE within the Charge Point", "tags": [ "resource / charge points" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "chargingProfile", "connectors", "notes" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "physicalReference": { "type": "string", "description": "The identifier that is presented to the users, so they can identify the EVSE at the location." }, "currentType": { "type": "string", "enum": [ "ac", "dc" ], "description": "Type of current available on the EVSE: - **ac**: Alternating Current (AC) charging - **dc**: Direct Current (DC) fast charging" }, "label": { "type": "string", "description": "The EVSE label will be exposed and visualized in the mobile application" }, "networkId": { "type": "string", "description": "The OCPP evse identifier (should be consecutive numbers starting from 1)" }, "status": { "type": "string", "enum": [ "enabled", "disabled", "out of order" ], "description": "For roaming EVSEs the status can only be updated if the option for manual management of EVSEs is enabled for the roaming CPO." }, "midMeterCertificationEndYear": { "type": "integer", "nullable": true, "description": "The mid meter certification end year." }, "tariffGroupId": { "type": "integer", "nullable": true, "description": "The ID of the tariff group attached to the EVSE. If the EVSE is not roaming and tariffGroupId is not specified, the default (free) tariff will be assigned. For roaming EVSEs the Tariff Group can only be updated if the option for manual management of EVSEs is enabled for the roaming CPO." }, "allowsReservation": { "type": "boolean", "description": "Manages whether reservations are allowed on this EVSE. Requires the Reservations to be activated for the system in order to enable for the EVSE." }, "bookingEnabled": { "type": "boolean", "description": "Indicates if the EVSE can be booked. Requires the Bookings to be activated for the operator and automatically enables allowsReservation when set to true." }, "monitoringEnabled": { "type": "boolean", "description": "When disabled, this EVSE will not be listed or counted in the Faults & connectivity loss widget or lens. The charge point will still appear for charge point-level faults (network loss, hardware faulted). Defaults to true." }, "powerOptions": { "type": "object", "properties": { "maxOutputVoltage": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Maximum output voltage for DC charging." }, "maxPower": { "type": "integer", "nullable": true, "description": "Maximum power of the EVSE in W (Watts)." }, "maxVoltage": { "type": "string", "enum": [ "230", "380", "400", "480", "120", "208", "240", "110-130", "220-240", "277" ], "nullable": true, "description": "The maximum intake (input) voltage of the EVSE. For the ac current type the output voltage is the same as this intake voltage, while for the dc current type the output voltage can differ and is exposed separately in maxOutputVoltage. The maxVoltage of a charge point can fluctuate. Hence, when creating a charge point in the system, the maxVoltage is given as a range. For OCPI purposes it maps as follows: 220-240 = 230 110-130 = 120 400 = 400 380 = 380" }, "maxAmperage": { "type": "number", "nullable": true }, "phases": { "type": "string", "enum": [ "single_phase", "three_phase", "split_phase" ], "nullable": true }, "phaseRotation": { "type": "string", "enum": [ "RST", "RTS", "SRT", "STR", "TRS", "TSR" ], "nullable": true, "description": "`R` stands for `L1`,
`S` - for `L2`
`T` - for `L3`
So for example `RST` = `L1`, `L2`, `L3`, while `RTS` = `L1`, `L3`, `L2`, etc.
We are deriving the connected phase from this property for single phase if connectedPhase is not provided. Please don't rely on this property anymore as this functionality will be turned of in near future. Pass the correct connectedPhase instead. If you pass both properties (connectedPhase and phaseRotation) only connectedPhase will be taken into consideration for determining the phase." }, "connectedPhase": { "type": "string", "enum": [ "L1", "L2", "L3", "L1_L2", "L1_L3", "L2_L3" ], "nullable": true, "description": "Specifies the active line conductors used in the circuit. - `L1_L2` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L2_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L2` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L3` - Valid when `phases` = `single_phase` in electrical configuration `star`" } } }, "externalId": { "type": "string" }, "capabilityOverrides": { "type": "object", "properties": { "rfidReader": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "creditCardPayable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "contactlessCardSupport": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "debitCardPayable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "chipCardSupport": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "pedTerminal": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "remoteStartStop": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "unlockCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "reservable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "chargingProfileCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "chargingPreferencesCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "startSessionConnectorRequired": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "tokenGroupCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" } }, "description": "Manual overrides for individual EVSE capabilities. Each property is independent. Send `force_enable` or `force_disable` to set or replace an override. Send `auto` to clear an existing override (the capability returns to automated detection). Omit a property to leave its current override unchanged." } } } } } }, "responses": { "200": { "description": "EVSE updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/evses/{evse}/connectors", "method": "GET", "operationId": "chargePointEvseConnectorsListing", "summary": "Charge Point / Evse / Connectors / Listing", "description": "Get a charge point evse's all connectors", "tags": [ "resource / charge points" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "externalId": { "type": "string", "description": "Lists only connectors with the specified external ID value." } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/evses/{evse}/connectors", "method": "POST", "operationId": "chargePointEvseConnectorCreate", "summary": "Charge Points / Evse / Connector / Create", "description": "Create a charge point evse's connector", "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "type1", "type2", "type3", "chademo", "ccs1", "ccs2", "schuko", "nacs", "cee16", "cee32", "j1772", "inductive", "nema-5-20", "type-e-french", "type-g-british", "type-j-swiss", "avcon", "gb-t-ac", "gb-t-dc", "chaoji", "nema-6-30", "nema-6-50", "mcs", "unknown" ], "description": "Type of connector available on the EVSE: - **type1**: Type 1 connector (SAE J1772 AC) - **type2**: Type 2 connector (IEC 62196-2 AC) - **type3**: Type 3 connector (IEC 62196-2 AC) - **chademo**: CHAdeMO DC fast charging - **ccs1**: Combined Charging System 1 (CCS1/Combo 1) - **ccs2**: Combined Charging System 2 (CCS2/Combo 2) - **schuko**: Standard European household socket - **nacs**: North American Charging Standard (Tesla) - **cee16**: CEE 16A industrial connector - **cee32**: CEE 32A industrial connector - **j1772**: SAE J1772 connector - **inductive**: Inductive/wireless charging - **nema-5-20**: Domestic M NEMA 5-20 Socket - **type-e-french**: French Type E socket - **type-g-british**: British Type G socket - **type-j-swiss**: Swiss Type J socket - **avcon**: AVCON connector (Australian standard) - **gb-t-ac**: GB/T AC connector (Chinese standard) - **gb-t-dc**: GB/T DC connector (Chinese standard) - **chaoji**: ChaoJi (CHAdeMO 3.0) - **nema-6-30**: NEMA 6-30 - **nema-6-50**: NEMA 6-50 - **mcs**: Megawatt Charging System (MCS) - **unknown**: Connector standard supplied by a 2.3.0+ OCPI roaming peer that is not part of the platform's recognised set. The original peer-supplied value is preserved internally and emitted on outbound OCPI flows." }, "format": { "type": "string", "enum": [ "socket", "cable" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "type" ] } } } }, "responses": { "201": { "description": "Created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/evses/{evse}/connectors/{connector}", "method": "GET", "operationId": "chargePointEvseConnectorRead", "summary": "Charge Points / Evse / Connector / Read", "description": "Get a charge point evse's connector", "tags": [ "resource / charge points" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/evses/{evse}/connectors/{connector}", "method": "DELETE", "operationId": "chargePointEvseConnectorDelete", "summary": "Charge Points / Evse / Connector / Delete", "description": "Delete a charge point evse's connector", "tags": [ "resource / charge points" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/evses/{evse}/connectors/{connector}", "method": "PATCH", "operationId": "chargePointEvseConnectorUpdate", "summary": "Charge Points / Evse / Connector / Update", "description": "Update a charge point evse's connector", "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "type1", "type2", "type3", "chademo", "ccs1", "ccs2", "schuko", "nacs", "cee16", "cee32", "j1772", "inductive", "nema-5-20", "type-e-french", "type-g-british", "type-j-swiss", "avcon", "gb-t-ac", "gb-t-dc", "chaoji", "nema-6-30", "nema-6-50", "mcs", "unknown" ], "description": "Type of connector available on the EVSE: - **type1**: Type 1 connector (SAE J1772 AC) - **type2**: Type 2 connector (IEC 62196-2 AC) - **type3**: Type 3 connector (IEC 62196-2 AC) - **chademo**: CHAdeMO DC fast charging - **ccs1**: Combined Charging System 1 (CCS1/Combo 1) - **ccs2**: Combined Charging System 2 (CCS2/Combo 2) - **schuko**: Standard European household socket - **nacs**: North American Charging Standard (Tesla) - **cee16**: CEE 16A industrial connector - **cee32**: CEE 32A industrial connector - **j1772**: SAE J1772 connector - **inductive**: Inductive/wireless charging - **nema-5-20**: Domestic M NEMA 5-20 Socket - **type-e-french**: French Type E socket - **type-g-british**: British Type G socket - **type-j-swiss**: Swiss Type J socket - **avcon**: AVCON connector (Australian standard) - **gb-t-ac**: GB/T AC connector (Chinese standard) - **gb-t-dc**: GB/T DC connector (Chinese standard) - **chaoji**: ChaoJi (CHAdeMO 3.0) - **nema-6-30**: NEMA 6-30 - **nema-6-50**: NEMA 6-50 - **mcs**: Megawatt Charging System (MCS) - **unknown**: Connector standard supplied by a 2.3.0+ OCPI roaming peer that is not part of the platform's recognised set. The original peer-supplied value is preserved internally and emitted on outbound OCPI flows." }, "format": { "type": "string", "enum": [ "socket", "cable" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } } } } }, "responses": { "200": { "description": "Updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/hardware-status-logs", "method": "GET", "operationId": "listChargePointHardwareStatusLogs", "summary": "Charge Point / Hardware Status Logs / Listing", "description": "Get paginated list of hardware status logs for a charge point with optional status and date filtering", "tags": [ "resource / charge points" ], "parameters": { "query": { "filter": { "description": "Filter options for charge point hardware status logs", "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "unavailable", "faulted" ], "example": "faulted", "description": "Charge point hardware status: - **available**: Charge point is available for use - **unavailable**: Charge point is not available for use - **faulted**: Charge point is in a faulted state" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Only list status logs created after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Only list status logs created before this datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "List of hardware status logs returned successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/latest-hardware-status-log", "method": "GET", "operationId": "getChargePointLatestHardwareStatusLog", "summary": "Charge Point / Latest Hardware Status Log", "description": "Get the latest hardware status log entry for a charge point", "tags": [ "resource / charge points" ], "responses": { "200": { "description": "Latest hardware status log returned successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/latest-network-status-log", "method": "GET", "operationId": "getChargePointLatestNetworkStatusLog", "summary": "Charge Point / Latest Network Status Log", "description": "Get the latest network status log entry for a charge point", "tags": [ "resource / charge points" ], "responses": { "200": { "description": "Latest network status log returned successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The requested resource wasn't found. This can occur if the specified charge point **exists but has never connected** to the system." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/network-status-logs", "method": "GET", "operationId": "listChargePointNetworkStatusLogs", "summary": "Charge Point / Network Status Logs / Listing", "description": "Get paginated list of network status logs for a charge point with optional date filtering", "tags": [ "resource / charge points" ], "parameters": { "query": { "filter": { "description": "Filter options for status logs", "schema": { "type": "object", "properties": { "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Only list status logs created after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Only list status logs created before this datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "List of network status logs returned successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The resource was not found, which can occur if the charge point exists but has never connected." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/notes", "method": "GET", "operationId": "chargePointNotesListing", "summary": "Charge Point / Notes / Listing", "description": "List all notes for a specific charge point. Notes are returned with pinned notes first, then ordered by creation date descending. **Required permission:** `Notes.view`", "tags": [ "resource / charge points" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "pinned": { "type": "boolean", "example": true, "description": "Filter by pinned status" }, "createdAfter": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z", "description": "Filter notes created on or after this ISO-8601 datetime" }, "createdBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes created on or before this ISO-8601 datetime" }, "updatedAfter": { "type": "string", "format": "date-time", "example": "2025-12-01T00:00:00Z", "description": "Filter notes updated on or after this ISO-8601 datetime (useful for delta sync)" }, "updatedBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes updated on or before this ISO-8601 datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/notes", "method": "POST", "operationId": "chargePointNoteCreate", "summary": "Charge Point / Note / Create", "description": "Create a new note for a specific charge point. **Required permission:** `Notes.create`", "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Important maintenance note", "description": "Short summary or title of the note (required)" }, "details": { "type": "string", "maxLength": 2000, "example": "This charge point requires monthly inspection due to high usage.", "description": "Detailed content of the note (optional)" }, "pinned": { "type": "boolean", "default": false, "example": false, "description": "Whether the note should be pinned (optional, defaults to false)" } }, "required": [ "summary" ] } } } }, "responses": { "201": { "description": "Note created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/notes/{note}", "method": "GET", "operationId": "chargePointNoteShow", "summary": "Charge Point / Note / Read", "description": "Get a specific note for a charge point. **Required permission:** `Notes.view`", "tags": [ "resource / charge points" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/notes/{note}", "method": "DELETE", "operationId": "chargePointNoteDelete", "summary": "Charge Point / Note / Delete", "description": "Delete a specific note from a charge point. Notes are permanently deleted (hard delete). **Required permission:** `Notes.delete`", "tags": [ "resource / charge points" ], "responses": { "204": { "description": "Note deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/notes/{note}", "method": "PATCH", "operationId": "chargePointNoteUpdate", "summary": "Charge Point / Note / Update", "description": "Update a specific note for a charge point. **Required permissions:** - `Notes.update` for updating summary and details - `Notes.pin` for updating the pinned field (in addition to Notes.update if other fields are included)", "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Updated maintenance note", "description": "Short summary or title of the note" }, "details": { "type": "string", "maxLength": 2000, "example": "Updated inspection schedule.", "nullable": true, "description": "Detailed content of the note. Send null to clear." }, "pinned": { "type": "boolean", "example": true, "description": "Whether the note should be pinned. Requires Notes.pin permission." } } } } } }, "responses": { "200": { "description": "Note updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/personal-smart-charging-preferences", "method": "GET", "operationId": "chargePointPersonalSmartChargingPreferencesRead", "summary": "Charge Point / Personal smart charging preferences / Read", "description": "Get personal smart charging preferences of the charge point", "tags": [ "resource / charge points" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/personal-smart-charging-preferences", "method": "POST", "operationId": "personalSmartChargingPreferencesUpdate", "summary": "Charge Point / Personal smart charging preferences / Update", "description": "Update personal smart charging preferences. Selecting the `charger_electricity_rate` type assigns the submitted `electricityRateId` to the charge point. Only two payloads remove the charge point's electricity rate, and both are subject to the 409 conflict described below. Sending `preferences.trackElectricityCosts` as `null` or as an empty object on `user_controlled_schedule` dissociates a rate that tracking electricity costs had created, while the request is handled. Leaving the charge point with no dynamic-price integration (`octopus_agile`, `octopus_go`, `nordpool`) while its current rate was created by one unlinks that rate asynchronously, after the response. Switching away from `charger_electricity_rate` to another type, and sending `enabled: false`, both leave the assigned rate in place. The update is rejected with 409 while removing the electricity rate would leave a reimbursement policy that resolves the rate from the charge point without a rate, whether the payload clears `preferences.trackElectricityCosts` or leaves no dynamic-price integration. The whole request is rejected: the submitted preferences are not stored, and the charge point keeps both its electricity rate and the dynamic-price integration the payload would have removed. Submitting `charger_electricity_rate` with a different `electricityRateId` replaces the rate and is allowed. The conflict clears only when the configuration changes: detach the policy, or keep an electricity rate on the charge point.", "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable or disable the smart charging from owner preferences" }, "type": { "type": "string", "enum": [ "user_controlled_schedule" ] }, "preferences": { "type": "object", "properties": { "startTime": { "type": "string", "format": "time", "description": "Start of preferred charging window which will be applied by default when no week day is chosen. Applicable for schedule mode" }, "endTime": { "type": "string", "format": "time", "description": "End of preferred charging window which will be applied by default when no week day is chosen. Applicable for schedule mode" }, "targetCharge": { "type": "object", "properties": { "minTargetChargeKwh": { "type": "number", "example": 10 }, "maxTargetChargeKwh": { "type": "number", "example": 20 } }, "nullable": true }, "trackElectricityCosts": { "type": "object", "properties": { "priceOffPeak": { "type": "number", "example": 1.3 }, "pricePeak": { "type": "number", "example": 0.9 } }, "nullable": true }, "weekDays": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Specify the day(s) for which the schedule will apply." }, "startTime": { "type": "string", "format": "time", "example": "16:00", "description": "Start of preferred charging window for chosen day(s)." }, "endTime": { "type": "string", "format": "time", "example": "23:00", "description": "End of preferred charging window for chosen day(s)." } }, "required": [ "days", "startTime", "endTime" ] } } }, "required": [ "startTime", "endTime" ] } }, "required": [ "type", "preferences" ] }, { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable or disable the smart charging from owner preferences" }, "type": { "type": "string", "enum": [ "solar" ] }, "preferences": { "type": "object", "properties": { "maxCurrentFromGrid": { "type": "number", "description": "The max current that can be taken from grid to ensure a stable charging process.Recommended options to use 0, 6, 8, 10, 12." }, "solarStableTime": { "type": "number", "description": "Shorter time means more precise solar availability detection but also more frequent charging on/off switching. Recommended options to use 30, 60, 120, 300, 600." } }, "required": [ "maxCurrentFromGrid", "solarStableTime" ] } }, "required": [ "type", "preferences" ] }, { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable or disable the smart charging from owner preferences" }, "type": { "type": "string", "enum": [ "octopus_agile" ] }, "integrationId": { "type": "integer" }, "preferences": { "type": "object", "properties": { "applicableTaxId": { "type": "integer", "description": "The ID of the applicable tax rate. Used to calculate correctly electricity costs shown to the user." }, "targetCharge": { "type": "object", "properties": { "departureTime": { "type": "string", "format": "time" }, "preconditioningTime": { "type": "integer", "description": "The time in minutes before departure when the charging will be performed with full power." }, "minTargetChargeKwh": { "type": "number", "example": 10 }, "maxTargetChargeKwh": { "type": "number", "example": 20 } }, "nullable": true }, "postCode": { "type": "string", "description": "User's postcode. Used to determine the applicable tariff." }, "priceThreshold": { "type": "number", "description": "The price per kWh threshold below which charging would commence." } }, "required": [ "postCode", "applicableTaxId", "priceThreshold" ] } }, "required": [ "type", "preferences", "integrationId" ] }, { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable or disable the smart charging from owner preferences" }, "type": { "type": "string", "enum": [ "octopus_go" ] }, "integrationId": { "type": "integer" }, "preferences": { "type": "object", "properties": { "applicableTaxId": { "type": "integer", "description": "The ID of the applicable tax rate. Used to calculate correctly electricity costs shown to the user." }, "targetCharge": { "type": "object", "properties": { "departureTime": { "type": "string", "format": "time" }, "preconditioningTime": { "type": "integer", "description": "The time in minutes before departure when the charging will be performed with full power." }, "minTargetChargeKwh": { "type": "number", "example": 10 }, "maxTargetChargeKwh": { "type": "number", "example": 20 } }, "nullable": true }, "postCode": { "type": "string", "description": "User's postcode. Used to determine the applicable tariff." }, "priceThreshold": { "type": "number", "description": "The price per kWh threshold below which charging would commence." } }, "required": [ "postCode", "applicableTaxId" ] } }, "required": [ "type", "preferences", "integrationId" ] }, { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable or disable the smart charging from owner preferences" }, "type": { "type": "string", "enum": [ "nordpool" ] }, "integrationId": { "type": "integer" }, "preferences": { "type": "object", "properties": { "location": { "type": "string", "enum": [ "GB1" ], "description": "The price region based on NordPool prices" }, "targetCharge": { "type": "object", "properties": { "departureTime": { "type": "string", "format": "time" }, "preconditioningTime": { "type": "integer", "description": "The time in minutes before departure when the charging will be performed with full power." }, "targetChargeKwh": { "type": "number", "example": 10 } }, "required": [ "targetChargeKwh", "departureTime" ] } }, "required": [ "location", "targetCharge" ] } }, "required": [ "type", "preferences", "integrationId" ] }, { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable or disable the smart charging from owner preferences" }, "type": { "type": "string", "enum": [ "charger_electricity_rate" ] }, "electricityRateId": { "type": "integer" }, "preferences": { "type": "object", "properties": { "solar": { "type": "boolean", "default": false, "description": "This boolean adds solar mode control for specific brands of chargers that are supported. E.g.: Some chargers support special keys in the charging profile which enables solar charging mode." }, "startTime": { "type": "string", "format": "time", "description": "Start of preferred charging window which will be applied by default when no week day is chosen." }, "endTime": { "type": "string", "format": "time", "description": "End of preferred charging window which will be applied by default when no week day is chosen." }, "targetCharge": { "type": "object", "properties": { "departureTime": { "type": "string", "format": "time" }, "preconditioningTime": { "type": "integer", "description": "The time in minutes before departure when the charging will be performed with full power." }, "targetChargeKwh": { "type": "number", "example": 10, "description": "The desired charge energy which will be achieved with the most optimal price." } }, "required": [ "departureTime", "targetChargeKwh" ] }, "weekDays": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Specify the day(s) for which the schedule will apply." }, "startTime": { "type": "string", "format": "time", "example": "16:00", "description": "Start of preferred charging window for chosen day(s)." }, "endTime": { "type": "string", "format": "time", "example": "23:00", "description": "End of preferred charging window for chosen day(s)." } }, "required": [ "days", "startTime", "endTime" ] } } }, "required": [ "startTime", "endTime", "targetCharge" ] } }, "required": [ "type", "electricityRateId", "preferences" ] }, { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Disable the smart charging from owner preferences" } }, "required": [ "enabled" ] } ] }, "examples": { "userControlledSchedule": { "summary": "User Controlled Schedule", "value": { "enabled": true, "type": "user_controlled_schedule", "preferences": { "startTime": "12:00", "endTime": "19:00", "targetCharge": { "minTargetChargeKwh": 10, "maxTargetChargeKwh": 25 }, "trackElectricityCosts": { "priceOffPeak": 1.3, "pricePeak": 0.9 }, "weekDays": [ { "days": [ "monday" ], "startTime": "16:00", "endTime": "23:00" }, { "days": [ "tuesday", "friday" ], "startTime": "17:00", "endTime": "22:00" } ] } } }, "solar": { "summary": "Solar", "value": { "enabled": true, "type": "solar", "preferences": { "maxCurrentFromGrid": 10, "solarStableTime": 60 } } }, "octopusAgile": { "summary": "Octopus Agile", "value": { "enabled": true, "type": "octopus_agile", "integrationId": 97, "preferences": { "applicableTaxId": 1, "postCode": "AA AAA", "priceThreshold": 9, "targetCharge": { "departureTime": "12:00", "preconditioningTime": 10, "minTargetChargeKwh": 10, "maxTargetChargeKwh": 25 } } } }, "octopusGo": { "summary": "Octopus Go", "value": { "enabled": true, "type": "octopus_go", "integrationId": 150, "preferences": { "applicableTaxId": 1, "postCode": "AA AAA", "targetCharge": { "departureTime": "12:00", "preconditioningTime": 10, "minTargetChargeKwh": 10, "maxTargetChargeKwh": 25 } } } }, "nordPool": { "summary": "Nordpool", "value": { "type": "nordpool", "integrationId": 95, "enabled": true, "preferences": { "location": "GB1", "targetCharge": { "departureTime": "12:00", "preconditioningTime": 10, "targetChargeKwh": 10 } } } }, "chargerElectricityRate": { "summary": "ChargerElectricityRate", "value": { "type": "charger_electricity_rate", "electricityRateId": 1, "enabled": true, "preferences": { "solar": true, "startTime": "12:00", "endTime": "19:00", "targetCharge": { "departureTime": "12:00", "preconditioningTime": 10, "targetChargeKwh": 10 }, "weekDays": [ { "days": [ "monday" ], "startTime": "16:00", "endTime": "23:00" }, { "days": [ "tuesday", "friday" ], "startTime": "17:00", "endTime": "22:00" } ] } } }, "personalModeDisabled": { "summary": "Disable", "value": { "enabled": false } } } } } }, "responses": { "201": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/shared-partners", "method": "GET", "operationId": "chargePointSharedPartnersListing", "summary": "Charge Point / Shared Partners / Listing", "description": "Get all Shared Partners of the Charge Point", "tags": [ "resource / charge points" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/shared-partners", "method": "PUT", "operationId": "chargePointSharedPartnersSync", "summary": "Charge Point / Shared Partners / Update", "description": "Set the Shared Partners of the Charge Point. Attach Shared Partners within the Charge Point. The charge point must have an owner associated and its `access_type` must be `private`. Grants access to this Partner to the charge point. This allows their invited users with access to private CPs to also access this CP. It also gives view-only access to the selected Partner's admins to this CP.", "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partnerIds": { "type": "array", "items": { "type": "integer" } } }, "required": [ "partnerIds" ] } } } }, "responses": { "204": { "description": "Given Partners are synchronized successfully to the Charge Point" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/shares", "method": "GET", "operationId": "chargePointSharesListing", "summary": "Charge point / shares / listing", "description": "Get all shares of the charge point", "tags": [ "resource / charge points" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/shares", "method": "POST", "operationId": "chargePointShareCreate", "summary": "Charge point / share / create", "description": "Create a new share within the charge point", "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "integer" } }, "required": [ "userId" ] } } } }, "responses": { "201": { "description": "Share created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/shares/{share}", "method": "GET", "operationId": "chargePointShareRead", "summary": "Charge point / share / read", "description": "Get a share from a charge point", "tags": [ "resource / charge points" ], "responses": { "200": { "description": "Share returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/shares/{share}", "method": "DELETE", "operationId": "charegPointShareDelete", "summary": "Charge point / share / delete", "description": "Delete a share", "tags": [ "resource / charge points" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/shares/{share}", "method": "PATCH", "operationId": "chargePointShareUpdate", "summary": "Charge point / share / update", "description": "Update a share", "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Share updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/charge-points/v2.0/{chargePoint}/smart-charging", "method": "POST", "operationId": "chargePointSmartChargingUpdate", "summary": "Charge Point / Smart Charging / Update", "description": "Update smart charging details for the charge point", "tags": [ "resource / charge points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "tod" ], "description": "`tod` - for public and private charge points. The maximum load for a specific time period during the day could be set - the charge point could be part of a dynamic load management circuit." }, "defaultChargePointMaxCurrent": { "type": "number", "description": "In amps. The max current would be used in the algorithm for the smart charging and wherever there is not a max current explicitly set." }, "circuitId": { "type": "integer", "nullable": true, "description": "The ID of the DLM Circuit to which the charge point is added (if any)." }, "periods": { "type": "array", "items": { "type": "object", "properties": { "weekDay": { "type": "string", "enum": [ "all", "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "description": "Specify the day for which the pricing would be valid." }, "elements": { "type": "array", "items": { "type": "object", "properties": { "startAt": { "type": "string", "format": "time", "example": "00:00", "description": "The 24-hour format should be used.
Example `00:00`" }, "endAt": { "type": "string", "format": "time", "example": "00:00", "description": "The 24-hour format should be used.
Example `01:00`" }, "maxCurrent": { "type": "number", "nullable": true } }, "required": [ "startAt", "endAt" ] } } }, "required": [ "weekDay", "elements" ] }, "description": "The time period must be the same for every single day through the week and should be always 60 min. The `startAt` and `endAt` must comply with this restriction." }, "preconditioningTime": { "type": "integer", "description": "The time in minutes before departure when the charging will be performed with full power." }, "minCurrent": { "type": "number", "nullable": true, "description": "minCurrent is always REQUIRED for `user_controlled_schedule`" }, "enableKeepAwake": { "type": "boolean", "nullable": true, "description": "For personal charge points. Keep the car awake during scheduled periods by continuously charging at a low current / power." }, "maxVoltage": { "type": "string", "enum": [ "230", "380", "400", "480", "120", "208", "240", "110-130", "220-240", "277" ] }, "electricalConfiguration": { "type": "string", "enum": [ "star", "delta" ], "default": "star", "description": "Defines the type of electrical configuration of the charge point. The available options are
`star` - Star/Wye (Y) (default)
`delta` - Delta (Δ)
" }, "phases": { "type": "string", "enum": [ "single_phase", "three_phase", "split_phase" ] }, "phaseRotation": { "type": "string", "enum": [ "RST", "RTS", "SRT", "STR", "TRS", "TSR" ], "nullable": true, "description": "`R` stands for `L1`,
`S` - for `L2`
`T` - for `L3`
So for example `RST` = `L1`, `L2`, `L3`, while `RTS` = `L1`, `L3`, `L2`, etc.
We are deriving the connected phase from this property for single phase if connectedPhase is not provided. Please don't rely on this property anymore as this functionality will be turned of in near future. Pass the correct connectedPhase instead. If you pass both properties (connectedPhase and phaseRotation) only connectedPhase will be taken into consideration for determining the phase." }, "connectedPhase": { "type": "string", "enum": [ "L1", "L2", "L3", "L1_L2", "L1_L3", "L2_L3" ], "nullable": true, "description": "Specifies the active line conductors used in the circuit. - `L1_L2` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L2_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L2` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L3` - Valid when `phases` = `single_phase` in electrical configuration `star`" }, "powerSharing": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether DC cabinet power sharing is enabled for the charge point." }, "managementMode": { "type": "string", "enum": [ "static", "dynamic" ], "nullable": true, "description": "Controls how the charge point allocates cabinet power across its DC outputs. `static` uses power modules dedicated to individual EVSEs; modules are not dynamically shared between EVSEs. `dynamic` shares power modules across EVSEs and allocates cabinet power in discrete steps defined by `moduleSizeKw`." }, "totalCabinetPowerKw": { "type": "integer", "minimum": 1, "nullable": true, "description": "Total power available from the DC cabinet, in kilowatts. Set to `null` to clear the configured value." }, "moduleSizeKw": { "type": "integer", "minimum": 1, "nullable": true, "description": "Power of one DC cabinet module, in kilowatts. Set to `null` to clear the configured value." } }, "description": "Updates the DC cabinet power-sharing configuration. Omitted properties retain their current values and explicit `null` clears a nullable property. The resulting configuration must provide `totalCabinetPowerKw` and `managementMode` when enabled. When `managementMode` is `dynamic`, `moduleSizeKw` is required, must not exceed `totalCabinetPowerKw`, and must divide `totalCabinetPowerKw` evenly. Updating this configuration for a charge point with active sessions triggers an immediate dynamic load management rebalance." } }, "required": [ "mode", "defaultChargePointMaxCurrent", "maxVoltage", "phases", "phaseRotation" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "dynamic" ], "description": "`dynamic` - for public and private charge points. The charge point could be part of a dynamic load management circuit." }, "defaultChargePointMaxCurrent": { "type": "number", "description": "In amps. The max current would be used in the algorithm for the smart charging and wherever there is not a max current explicitly set." }, "preconditioningTime": { "type": "integer", "description": "The time in minutes before departure when the charging will be performed with full power." }, "circuitId": { "type": "integer", "nullable": true, "description": "The ID of the DLM Circuit to which the charge point is added (if any)." }, "minCurrent": { "type": "number", "nullable": true, "description": "minCurrent is always REQUIRED for `user_controlled_schedule`" }, "enableKeepAwake": { "type": "boolean", "nullable": true, "description": "For personal charge points. Keep the car awake during scheduled periods by continuously charging at a low current / power." }, "maxVoltage": { "type": "string", "enum": [ "230", "380", "400", "480", "120", "208", "240", "110-130", "220-240", "277" ] }, "electricalConfiguration": { "type": "string", "enum": [ "star", "delta" ], "default": "star", "description": "Defines the type of electrical configuration of the charge point. The available options are
`star` - Star/Wye (Y) (default)
`delta` - Delta (Δ)
" }, "phases": { "type": "string", "enum": [ "single_phase", "three_phase", "split_phase" ] }, "phaseRotation": { "type": "string", "enum": [ "RST", "RTS", "SRT", "STR", "TRS", "TSR" ], "nullable": true, "description": "`R` stands for `L1`,
`S` - for `L2`
`T` - for `L3`
So for example `RST` = `L1`, `L2`, `L3`, while `RTS` = `L1`, `L3`, `L2`, etc.
We are deriving the connected phase from this property for single phase if connectedPhase is not provided. Please don't rely on this property anymore as this functionality will be turned of in near future. Pass the correct connectedPhase instead. If you pass both properties (connectedPhase and phaseRotation) only connectedPhase will be taken into consideration for determining the phase." }, "connectedPhase": { "type": "string", "enum": [ "L1", "L2", "L3", "L1_L2", "L1_L3", "L2_L3" ], "nullable": true, "description": "Specifies the active line conductors used in the circuit. - `L1_L2` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L2_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L2` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L3` - Valid when `phases` = `single_phase` in electrical configuration `star`" }, "powerSharing": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether DC cabinet power sharing is enabled for the charge point." }, "managementMode": { "type": "string", "enum": [ "static", "dynamic" ], "nullable": true, "description": "Controls how the charge point allocates cabinet power across its DC outputs. `static` uses power modules dedicated to individual EVSEs; modules are not dynamically shared between EVSEs. `dynamic` shares power modules across EVSEs and allocates cabinet power in discrete steps defined by `moduleSizeKw`." }, "totalCabinetPowerKw": { "type": "integer", "minimum": 1, "nullable": true, "description": "Total power available from the DC cabinet, in kilowatts. Set to `null` to clear the configured value." }, "moduleSizeKw": { "type": "integer", "minimum": 1, "nullable": true, "description": "Power of one DC cabinet module, in kilowatts. Set to `null` to clear the configured value." } }, "description": "Updates the DC cabinet power-sharing configuration. Omitted properties retain their current values and explicit `null` clears a nullable property. The resulting configuration must provide `totalCabinetPowerKw` and `managementMode` when enabled. When `managementMode` is `dynamic`, `moduleSizeKw` is required, must not exceed `totalCabinetPowerKw`, and must divide `totalCabinetPowerKw` evenly. Updating this configuration for a charge point with active sessions triggers an immediate dynamic load management rebalance." } }, "required": [ "mode", "defaultChargePointMaxCurrent", "maxVoltage", "phases", "phaseRotation" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "user_schedule" ], "description": "`user_schedule` - for personal charge points. The maximum power load will be defined on the EVSE level. The charge point owner could manually create a charging schedule." }, "defaultChargePointMaxCurrent": { "type": "number", "description": "In amps. The max current would be used in the algorithm for the smart charging and wherever there is not a max current explicitly set." }, "preconditioningTime": { "type": "integer", "description": "The time in minutes before departure when the charging will be performed with full power." }, "circuitId": { "type": "integer", "nullable": true, "description": "The ID of the DLM Circuit to which the charge point is added (if any)." }, "minCurrent": { "type": "number", "nullable": true, "description": "minCurrent is always REQUIRED for `user_controlled_schedule`" }, "enableKeepAwake": { "type": "boolean", "nullable": true, "description": "For personal charge points. Keep the car awake during scheduled periods by continuously charging at a low current / power." }, "maxVoltage": { "type": "string", "enum": [ "230", "380", "400", "480", "120", "208", "240", "110-130", "220-240", "277" ] }, "electricalConfiguration": { "type": "string", "enum": [ "star", "delta" ], "default": "star", "description": "Defines the type of electrical configuration of the charge point. The available options are
`star` - Star/Wye (Y) (default)
`delta` - Delta (Δ)
" }, "phases": { "type": "string", "enum": [ "single_phase", "three_phase", "split_phase" ] }, "phaseRotation": { "type": "string", "enum": [ "RST", "RTS", "SRT", "STR", "TRS", "TSR" ], "nullable": true, "description": "`R` stands for `L1`,
`S` - for `L2`
`T` - for `L3`
So for example `RST` = `L1`, `L2`, `L3`, while `RTS` = `L1`, `L3`, `L2`, etc.
We are deriving the connected phase from this property for single phase if connectedPhase is not provided. Please don't rely on this property anymore as this functionality will be turned of in near future. Pass the correct connectedPhase instead. If you pass both properties (connectedPhase and phaseRotation) only connectedPhase will be taken into consideration for determining the phase." }, "allowDynamicLoadManagement": { "type": "boolean", "description": "When selected, the Charge Point can be added to a DLM circuit." }, "connectedPhase": { "type": "string", "enum": [ "L1", "L2", "L3", "L1_L2", "L1_L3", "L2_L3" ], "nullable": true, "description": "Specifies the active line conductors used in the circuit. - `L1_L2` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L2_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L2` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L3` - Valid when `phases` = `single_phase` in electrical configuration `star`" }, "powerSharing": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether DC cabinet power sharing is enabled for the charge point." }, "managementMode": { "type": "string", "enum": [ "static", "dynamic" ], "nullable": true, "description": "Controls how the charge point allocates cabinet power across its DC outputs. `static` uses power modules dedicated to individual EVSEs; modules are not dynamically shared between EVSEs. `dynamic` shares power modules across EVSEs and allocates cabinet power in discrete steps defined by `moduleSizeKw`." }, "totalCabinetPowerKw": { "type": "integer", "minimum": 1, "nullable": true, "description": "Total power available from the DC cabinet, in kilowatts. Set to `null` to clear the configured value." }, "moduleSizeKw": { "type": "integer", "minimum": 1, "nullable": true, "description": "Power of one DC cabinet module, in kilowatts. Set to `null` to clear the configured value." } }, "description": "Updates the DC cabinet power-sharing configuration. Omitted properties retain their current values and explicit `null` clears a nullable property. The resulting configuration must provide `totalCabinetPowerKw` and `managementMode` when enabled. When `managementMode` is `dynamic`, `moduleSizeKw` is required, must not exceed `totalCabinetPowerKw`, and must divide `totalCabinetPowerKw` evenly. Updating this configuration for a charge point with active sessions triggers an immediate dynamic load management rebalance." } }, "required": [ "mode", "defaultChargePointMaxCurrent", "minCurrent", "enableKeepAwake", "maxVoltage", "phases", "phaseRotation" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "disabled" ], "description": "`disabled` - no smart charging is available for the charge point" }, "preconditioningTime": { "type": "integer", "description": "The time in minutes before departure when the charging will be performed with full power." }, "powerSharing": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether DC cabinet power sharing is enabled for the charge point." }, "managementMode": { "type": "string", "enum": [ "static", "dynamic" ], "nullable": true, "description": "Controls how the charge point allocates cabinet power across its DC outputs. `static` uses power modules dedicated to individual EVSEs; modules are not dynamically shared between EVSEs. `dynamic` shares power modules across EVSEs and allocates cabinet power in discrete steps defined by `moduleSizeKw`." }, "totalCabinetPowerKw": { "type": "integer", "minimum": 1, "nullable": true, "description": "Total power available from the DC cabinet, in kilowatts. Set to `null` to clear the configured value." }, "moduleSizeKw": { "type": "integer", "minimum": 1, "nullable": true, "description": "Power of one DC cabinet module, in kilowatts. Set to `null` to clear the configured value." } }, "description": "Updates the DC cabinet power-sharing configuration. Omitted properties retain their current values and explicit `null` clears a nullable property. The resulting configuration must provide `totalCabinetPowerKw` and `managementMode` when enabled. When `managementMode` is `dynamic`, `moduleSizeKw` is required, must not exceed `totalCabinetPowerKw`, and must divide `totalCabinetPowerKw` evenly. Updating this configuration for a charge point with active sessions triggers an immediate dynamic load management rebalance." } }, "required": [ "mode" ] } ] } } } }, "responses": { "201": { "description": "Updated smart charging details" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/circuits/v1.0", "method": "GET", "operationId": "circuitsListingDeprecated", "summary": "Circuits / Listing", "description": "Get all circuits", "deprecated": true, "tags": [ "resource / circuits" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/circuits/v1.0", "method": "POST", "operationId": "circuitCreateDeprecated", "summary": "Circuit / Create", "description": "Create new circuits", "deprecated": true, "tags": [ "resource / circuits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phases": { "type": "string", "enum": [ "1", "3" ] }, "maxCurrent": { "type": "number", "minimum": 0, "description": "In amps" }, "minChargePointCurrent": { "type": "number", "minimum": 0, "description": "In amps. The minimum" }, "setSessionLimitToZeroOnIdle": { "type": "boolean", "description": "Set charger limit to 0 if an idle period starts" }, "chargePoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "maxCurrent": { "type": "number", "description": "in Amps" }, "phases": { "type": "string", "enum": [ "1", "3" ] }, "inputVoltage": { "type": "string", "enum": [ "110-130", "220-240", "380", "400" ], "description": "use 380/400 for 3-phase connected CPs" }, "phaseRotation": { "type": "string", "enum": [ "L1", "L2", "L3", "RST", "RTS", "SRT", "STR", "TRS", "TSR" ], "description": "Use L* for single phase CP to note the connected phase" } }, "required": [ "id", "maxCurrent", "phases", "inputVoltage", "phaseRotation" ] } }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "id", "name", "phases", "maxCurrent", "chargePoints" ] } } } }, "responses": { "201": { "description": "Circuit created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/circuits/v1.0/{dlmCircuit}", "method": "GET", "operationId": "circuitReadDeprecated", "summary": "Circuit / Read", "description": "Get a circuit", "deprecated": true, "tags": [ "resource / circuits" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/circuits/v1.0/{dlmCircuit}", "method": "DELETE", "operationId": "circuitDeleteDeprecated", "summary": "Circuit / Delete", "description": "Delete a circuit. If the circuit is part of a disabled flexibility asset, both the circuit and the associated flexibility asset will be deleted. If the circuit is part of an enabled flexibility asset, the deletion will be rejected with a 409 Conflict status code.", "deprecated": true, "tags": [ "resource / circuits" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "409": { "description": "The circuit is managed by an enabled flexibility asset and cannot be deleted." } } }, { "path": "/public-api/resources/circuits/v1.0/{dlmCircuit}", "method": "PATCH", "operationId": "circuitUpdateDeprecated", "summary": "Circuit / Update", "description": "Update a circuit", "deprecated": true, "tags": [ "resource / circuits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phases": { "type": "string", "enum": [ "1", "3" ] }, "maxCurrent": { "type": "number", "minimum": 0, "description": "In Amps" }, "minChargePointCurrent": { "type": "number", "minimum": 0, "description": "In Amps. The minimum" }, "setSessionLimitToZeroOnIdle": { "type": "boolean", "description": "Set charger limit to 0 if an idle period starts" }, "chargePoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "maxCurrent": { "type": "number", "description": "in Amps" }, "phases": { "type": "string", "enum": [ "1", "3" ] }, "inputVoltage": { "type": "string", "enum": [ "110-130", "220-240", "380", "400" ], "description": "use 380/400 for 3-phase connected CPs" }, "phaseRotation": { "type": "string", "enum": [ "L1", "L2", "L3", "RST", "RTS", "SRT", "STR", "TRS", "TSR" ], "description": "Use L* for single phase CP to note the connected phase" } }, "required": [ "id", "maxCurrent", "phases", "inputVoltage", "phaseRotation" ] } }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } } } } } }, "responses": { "200": { "description": "Circuit updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/circuits/v1.0/{dlmCircuit}/consumption", "method": "GET", "operationId": "circuitConsumptionAllPhasesDeprecated", "summary": "Circuit / Consumption (all phases)", "description": "Get the consumption of a circuit for each phase", "deprecated": true, "tags": [ "resource / circuits" ], "parameters": { "path": { "dlmCircuit": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/circuits/v1.0/{dlmCircuit}/consumption/{phase}", "method": "GET", "operationId": "circuitConsumptionPhaseDeprecated", "summary": "Circuit / Consumption (phase)", "description": "Get the consumption of a circuit for a single phase", "deprecated": true, "tags": [ "resource / circuits" ], "parameters": { "path": { "dlmCircuit": { "type": "integer", "required": true }, "phase": { "schema": { "type": "string", "enum": [ "L1", "L2", "L3" ] }, "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/circuits/v2.0", "method": "GET", "operationId": "circuitsListing", "summary": "Circuits / Listing", "description": "Get all circuits", "tags": [ "resource / circuits" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "chargePointPriorities", "userPriorities", "socPriorities", "consumption", "unmanagedLoad" ] } } }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the circuits that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the circuits that were last updated on and before this datetime" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the circuit records that were created on and after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the circuit records that were created on and before this datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/circuits/v2.0", "method": "POST", "operationId": "circuitCreate", "summary": "Circuit / Create", "description": "Create a new circuit", "tags": [ "resource / circuits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "name": { "type": "string" }, "parentCircuitId": { "type": "integer", "nullable": true, "description": "Specify parent circuit in Multi-level DLM. Circuits used in flexibility assets or using load balancing integration can not be used in Multi-level DLM." }, "phases": { "type": "string", "enum": [ "single_phase", "three_phase", "split_phase" ] }, "phaseRotation": { "type": "string", "enum": [ "RST", "RTS", "SRT", "STR", "TRS", "TSR" ], "nullable": true, "description": "`R` stands for `L1`,
`S` - for `L2`
`T` - for `L3`
So for example `RST` = `L1`, `L2`, `L3`, while `RTS` = `L1`, `L3`, `L2`, etc.
We are deriving the connected phase from this property for single phase if connectedPhase is not provided. Please don't rely on this property anymore as this functionality will be turned of in near future. Pass the correct connectedPhase instead. If you pass both properties (connectedPhase and phaseRotation) only connectedPhase will be taken into consideration for determining the phase." }, "connectedPhase": { "type": "string", "enum": [ "L1", "L2", "L3", "L1_L2", "L1_L3", "L2_L3" ], "nullable": true, "description": "Specifies the active line conductors used in the circuit. - `L1_L2` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L2_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L2` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L3` - Valid when `phases` = `single_phase` in electrical configuration `star`" }, "electricalConfiguration": { "type": "string", "enum": [ "star", "delta" ], "default": "star", "description": "Defines the type of electrical configuration of the charge point. The available options are
`star` - Star/Wye (Y) (default)
`delta` - Delta (Δ)
" }, "maxVoltage": { "type": "string", "enum": [ "230", "380", "400", "480", "120", "208", "240", "110-130", "220-240", "277" ], "nullable": true }, "maxCurrent": { "type": "number", "description": "The current (A) limit for the whole circuit. This would usually be the circuit breaker rated current." }, "minChargePointCurrent": { "type": "number", "nullable": true, "description": "Defines what is the lowest current (A) allowed per charge point. New sessions cannot start if any of the existing ones has to be lowered to less than the set minimum rate. This is to ensure that a connected car vehicle actually charge because the vehicles have a minimum charging rate below which they would not accept the charge. If left empty, there is no minimum." }, "applyMinimumCurrentOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled, new sessions start at the configured minimum current (minChargePointCurrent). This improves user experience but bypasses initial DLM safety checks. Use with caution: In offline scenarios, the DLM cannot limit the load, creating a high risk of circuit overload. Only enable this option if your site has a stable internet connection and the electrical circuit has significant spare capacity to handle all charge points operating at their minimum current simultaneously." }, "applyFcfsLoadManagementStrategy": { "type": "boolean", "default": false, "description": "When enabled, on charge points with multiple EVSEs, only the first active session receives current. Any other session on the same charge point waits until the first session ends." }, "setSessionLimitToZeroOnIdle": { "type": "boolean", "description": "Sets the limit to 0 when the session enters an idle period." }, "electricityMeterId": { "type": "number", "nullable": true, "description": "The ID of the Electricity Meter linked to the circuit (if any)." }, "offlineReservedCurrent": { "type": "number", "nullable": true, "description": "The current (A) reserved for other loads on the circuit (non-managed loads) when the Electricity Meter is offline." }, "loadBalancingIntegration": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "The id of the load balancing integration (can be found in the admin panel). Provide `null` if you want to disable any load balancing integration and revert back to the built-in load balancing." }, "fields": { "oneOf": [ { "type": "object", "properties": { "startDate": { "type": "string", "format": "date", "example": "2025-02-18", "nullable": true, "description": "DREEV specific. Reporting and accepting charging schedules will commence at this date." } } }, { "type": "object", "properties": { "installationId": { "type": "string", "format": "uuid", "example": "0194db65-2791-70ae-9575-89959f57d915", "description": "Zaptec specific. Installation ID inside Zaptec system, used for identifying the corresponding circuit." } }, "required": [ "installationId" ] } ] } }, "nullable": true, "description": "The selected integration enables the system to receive and apply third-party charging limits to the chargers added in the circuit." } }, "required": [ "name", "phases", "maxCurrent" ] } } } }, "responses": { "201": { "description": "Circuit created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}", "method": "GET", "operationId": "circuitRead", "summary": "Circuit / Read", "description": "Get a circuit", "tags": [ "resource / circuits" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "chargePointPriorities", "userPriorities", "socPriorities", "consumption", "unmanagedLoad", "schedule" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}", "method": "DELETE", "operationId": "circuitDelete", "summary": "Circuit / Delete", "description": "Delete a circuit. If the circuit is part of a disabled flexibility asset, both the circuit and the associated flexibility asset will be deleted. If the circuit is part of an enabled flexibility asset, the deletion will be rejected with a 409 Conflict status code.", "tags": [ "resource / circuits" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The circuit is managed by an enabled flexibility asset and cannot be deleted." } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}", "method": "PATCH", "operationId": "circuitUpdate", "summary": "Circuit / Update", "description": "Update a circuit", "tags": [ "resource / circuits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "name": { "type": "string" }, "parentCircuitId": { "type": "integer", "nullable": true, "description": "Specify parent circuit in Multi-level DLM. Circuits used in flexibility assets or using load balancing integration can not be used in Multi-level DLM." }, "phases": { "type": "string", "enum": [ "single_phase", "three_phase", "split_phase" ] }, "phaseRotation": { "type": "string", "enum": [ "RST", "RTS", "SRT", "STR", "TRS", "TSR" ], "nullable": true, "description": "`R` stands for `L1`,
`S` - for `L2`
`T` - for `L3`
So for example `RST` = `L1`, `L2`, `L3`, while `RTS` = `L1`, `L3`, `L2`, etc.
We are deriving the connected phase from this property for single phase if connectedPhase is not provided. Please don't rely on this property anymore as this functionality will be turned of in near future. Pass the correct connectedPhase instead. If you pass both properties (connectedPhase and phaseRotation) only connectedPhase will be taken into consideration for determining the phase." }, "connectedPhase": { "type": "string", "enum": [ "L1", "L2", "L3", "L1_L2", "L1_L3", "L2_L3" ], "nullable": true, "description": "Specifies the active line conductors used in the circuit. - `L1_L2` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L2_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L2` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L3` - Valid when `phases` = `single_phase` in electrical configuration `star`" }, "electricalConfiguration": { "type": "string", "enum": [ "star", "delta" ], "default": "star", "description": "Defines the type of electrical configuration of the charge point. The available options are
`star` - Star/Wye (Y) (default)
`delta` - Delta (Δ)
" }, "maxVoltage": { "type": "string", "enum": [ "230", "380", "400", "480", "120", "208", "240", "110-130", "220-240", "277" ], "nullable": true }, "maxCurrent": { "type": "number", "description": "The current (A) limit for the whole circuit. This would usually be the circuit breaker rated current." }, "minChargePointCurrent": { "type": "number", "nullable": true, "description": "Defines what is the lowest current (A) allowed per charge point. New sessions cannot start if any of the existing ones has to be lowered to less than the set minimum rate. This is to ensure that a connected car vehicle actually charge because the vehicles have a minimum charging rate below which they would not accept the charge. If left empty, there is no minimum." }, "applyMinimumCurrentOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled, new sessions start at the configured minimum current (minChargePointCurrent). This improves user experience but bypasses initial DLM safety checks. Use with caution: In offline scenarios, the DLM cannot limit the load, creating a high risk of circuit overload. Only enable this option if your site has a stable internet connection and the electrical circuit has significant spare capacity to handle all charge points operating at their minimum current simultaneously." }, "applyFcfsLoadManagementStrategy": { "type": "boolean", "default": false, "description": "When enabled, on charge points with multiple EVSEs, only the first active session receives current. Any other session on the same charge point waits until the first session ends." }, "setSessionLimitToZeroOnIdle": { "type": "boolean", "description": "Sets the limit to 0 when the session enters an idle period." }, "electricityMeterId": { "type": "number", "nullable": true, "description": "The ID of the Electricity Meter linked to the circuit (if any)." }, "offlineReservedCurrent": { "type": "number", "nullable": true, "description": "The current (A) reserved for other loads on the circuit (non-managed loads) when the Electricity Meter is offline." }, "loadBalancingIntegration": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "The id of the load balancing integration (can be found in the admin panel). Provide `null` if you want to disable any load balancing integration and revert back to the built-in load balancing." }, "fields": { "oneOf": [ { "type": "object", "properties": { "startDate": { "type": "string", "format": "date", "example": "2025-02-18", "nullable": true, "description": "DREEV specific. Reporting and accepting charging schedules will commence at this date." } } }, { "type": "object", "properties": { "installationId": { "type": "string", "format": "uuid", "example": "0194db65-2791-70ae-9575-89959f57d915", "description": "Zaptec specific. Installation ID inside Zaptec system, used for identifying the corresponding circuit." } }, "required": [ "installationId" ] } ] } }, "nullable": true, "description": "The selected integration enables the system to receive and apply third-party charging limits to the chargers added in the circuit." } } } } } }, "responses": { "200": { "description": "Circuit updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}/charge-point-priorities", "method": "GET", "operationId": "circuitChargePointPrioritiesListing", "summary": "Circuit / Charge Point Priorities / Listing", "description": "Get all circuit's charge point priorities", "tags": [ "resource / circuits" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}/consumption", "method": "GET", "operationId": "circuitConsumption", "summary": "Circuit / Consumption", "description": "Get the consumption of a circuit for each phase", "tags": [ "resource / circuits" ], "parameters": { "path": { "circuit": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}/schedule", "method": "GET", "operationId": "circuitScheduleRead", "summary": "Circuit / Schedule / Read", "description": "Get a circuit's schedule configuration", "tags": [ "resource / circuits" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "No schedule configured for this circuit" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}/schedule", "method": "PUT", "operationId": "circuitScheduleCreateOrUpdate", "summary": "Circuit / Schedule / Create or Update", "description": "Create or replace a circuit's schedule configuration", "tags": [ "resource / circuits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduleType": { "type": "string", "enum": [ "daily", "weekly" ], "description": "Schedule type for time-based current reduction: - **daily**: Same schedule periods apply every day - **weekly**: Different schedule periods can be configured for each day of the week" }, "schedule": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "08:00", "description": "Start time of the period in HH:MM format (24-hour)." }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "18:00", "description": "End time of the period in HH:MM format (24-hour). Must be after the start time (periods cannot span midnight)." }, "maxCurrent": { "type": "number", "format": "float", "minimum": 0, "example": 16, "description": "Maximum current (A) available during this period. Must not exceed the circuit's maximum current." } }, "required": [ "start", "end", "maxCurrent" ], "description": "A time period within a schedule during which reduced current applies. The period defines when the circuit's maximum available current is limited." }, "description": "A daily schedule consisting of time periods that apply every day. Periods within the schedule must not overlap." }, { "type": "object", "properties": { "monday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "08:00", "description": "Start time of the period in HH:MM format (24-hour)." }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "18:00", "description": "End time of the period in HH:MM format (24-hour). Must be after the start time (periods cannot span midnight)." }, "maxCurrent": { "type": "number", "format": "float", "minimum": 0, "example": 16, "description": "Maximum current (A) available during this period. Must not exceed the circuit's maximum current." } }, "required": [ "start", "end", "maxCurrent" ], "description": "A time period within a schedule during which reduced current applies. The period defines when the circuit's maximum available current is limited." }, "description": "A daily schedule consisting of time periods that apply every day. Periods within the schedule must not overlap." }, "tuesday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "08:00", "description": "Start time of the period in HH:MM format (24-hour)." }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "18:00", "description": "End time of the period in HH:MM format (24-hour). Must be after the start time (periods cannot span midnight)." }, "maxCurrent": { "type": "number", "format": "float", "minimum": 0, "example": 16, "description": "Maximum current (A) available during this period. Must not exceed the circuit's maximum current." } }, "required": [ "start", "end", "maxCurrent" ], "description": "A time period within a schedule during which reduced current applies. The period defines when the circuit's maximum available current is limited." }, "description": "A daily schedule consisting of time periods that apply every day. Periods within the schedule must not overlap." }, "wednesday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "08:00", "description": "Start time of the period in HH:MM format (24-hour)." }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "18:00", "description": "End time of the period in HH:MM format (24-hour). Must be after the start time (periods cannot span midnight)." }, "maxCurrent": { "type": "number", "format": "float", "minimum": 0, "example": 16, "description": "Maximum current (A) available during this period. Must not exceed the circuit's maximum current." } }, "required": [ "start", "end", "maxCurrent" ], "description": "A time period within a schedule during which reduced current applies. The period defines when the circuit's maximum available current is limited." }, "description": "A daily schedule consisting of time periods that apply every day. Periods within the schedule must not overlap." }, "thursday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "08:00", "description": "Start time of the period in HH:MM format (24-hour)." }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "18:00", "description": "End time of the period in HH:MM format (24-hour). Must be after the start time (periods cannot span midnight)." }, "maxCurrent": { "type": "number", "format": "float", "minimum": 0, "example": 16, "description": "Maximum current (A) available during this period. Must not exceed the circuit's maximum current." } }, "required": [ "start", "end", "maxCurrent" ], "description": "A time period within a schedule during which reduced current applies. The period defines when the circuit's maximum available current is limited." }, "description": "A daily schedule consisting of time periods that apply every day. Periods within the schedule must not overlap." }, "friday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "08:00", "description": "Start time of the period in HH:MM format (24-hour)." }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "18:00", "description": "End time of the period in HH:MM format (24-hour). Must be after the start time (periods cannot span midnight)." }, "maxCurrent": { "type": "number", "format": "float", "minimum": 0, "example": 16, "description": "Maximum current (A) available during this period. Must not exceed the circuit's maximum current." } }, "required": [ "start", "end", "maxCurrent" ], "description": "A time period within a schedule during which reduced current applies. The period defines when the circuit's maximum available current is limited." }, "description": "A daily schedule consisting of time periods that apply every day. Periods within the schedule must not overlap." }, "saturday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "08:00", "description": "Start time of the period in HH:MM format (24-hour)." }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "18:00", "description": "End time of the period in HH:MM format (24-hour). Must be after the start time (periods cannot span midnight)." }, "maxCurrent": { "type": "number", "format": "float", "minimum": 0, "example": 16, "description": "Maximum current (A) available during this period. Must not exceed the circuit's maximum current." } }, "required": [ "start", "end", "maxCurrent" ], "description": "A time period within a schedule during which reduced current applies. The period defines when the circuit's maximum available current is limited." }, "description": "A daily schedule consisting of time periods that apply every day. Periods within the schedule must not overlap." }, "sunday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "08:00", "description": "Start time of the period in HH:MM format (24-hour)." }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "18:00", "description": "End time of the period in HH:MM format (24-hour). Must be after the start time (periods cannot span midnight)." }, "maxCurrent": { "type": "number", "format": "float", "minimum": 0, "example": 16, "description": "Maximum current (A) available during this period. Must not exceed the circuit's maximum current." } }, "required": [ "start", "end", "maxCurrent" ], "description": "A time period within a schedule during which reduced current applies. The period defines when the circuit's maximum available current is limited." }, "description": "A daily schedule consisting of time periods that apply every day. Periods within the schedule must not overlap." } }, "required": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "description": "A weekly schedule with separate time periods for each day of the week. Each day can have multiple non-overlapping periods. All days must be provided, even if empty." } ], "description": "Schedule configuration for time-based current reduction. The structure depends on scheduleType: - When scheduleType is `daily`: An array of time periods that apply every day. - When scheduleType is `weekly`: An object with day-of-week keys (monday through sunday), each containing an array of time periods. Periods within a day must not overlap and cannot span midnight." }, "scheduleLimitUnit": { "type": "string", "enum": [ "amps", "kilowatts" ], "description": "Unit for interpreting schedule period `maxCurrent` values, and the upper bound that applies to each period: - **amps**: Per-phase amperes (A); must not exceed the circuit's `maxCurrent`. - **kilowatts**: Total kilowatts (kW); must not exceed the circuit's derived kW capacity computed from `maxCurrent × phases × maxVoltage`." } }, "required": [ "scheduleType", "schedule" ] } } } }, "responses": { "200": { "description": "Schedule created or updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}/schedule", "method": "DELETE", "operationId": "circuitScheduleDelete", "summary": "Circuit / Schedule / Delete", "description": "Clear a circuit's schedule configuration", "tags": [ "resource / circuits" ], "responses": { "204": { "description": "Schedule deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}/soc-priorities", "method": "GET", "operationId": "circuitSocPrioritiesListing", "summary": "Circuit / SoC Priorities / Listing", "description": "Get a circuit's SoC priority", "tags": [ "resource / circuits" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}/unmanaged-load", "method": "GET", "operationId": "circuitUnmanagedLoadRead", "summary": "Circuit / Unmanaged Load / Read", "description": "Get a circuit's unmanaged load", "tags": [ "resource / circuits" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}/user-priorities", "method": "GET", "operationId": "circuitUserPrioritiesListing", "summary": "Circuits / User Priorities / Listing", "description": "Get all circuit's user priorities", "tags": [ "resource / circuits" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}/user-priorities", "method": "POST", "operationId": "circuitUserPriorityCreate", "summary": "Circuits / User Priority / Create", "description": "Create a circuit's user priority", "tags": [ "resource / circuits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "targetId": { "type": "integer", "description": "The ID of the User Group the user must be part of or the ID of the Partner from which the user must have an invite from, for the set priority apply for the session." }, "type": { "type": "string", "enum": [ "partner", "userGroup" ] }, "priority": { "type": "number", "format": "float", "minimum": 0, "description": "The priority where 1 is equal to anyone else, 2 is twice as important, 0.5 is half as important." } }, "required": [ "targetId", "type", "priority" ] } } } }, "responses": { "201": { "description": "Circuit's user priority created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}/user-priorities/{userPriority}", "method": "GET", "operationId": "circuitUserPriorityRead", "summary": "Circuits / User Priority / Read", "description": "Get a circuit's user priority", "tags": [ "resource / circuits" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}/user-priorities/{userPriority}", "method": "DELETE", "operationId": "circuitUserPriorityDelete", "summary": "Circuits / User Priority / Delete", "description": "Delete a circuit's user priority", "tags": [ "resource / circuits" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/circuits/v2.0/{circuit}/user-priorities/{userPriority}", "method": "PATCH", "operationId": "circuitUserPriorityUpdate", "summary": "Circuits / User Priority / Update", "description": "Update a circuit's user priority", "tags": [ "resource / circuits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "targetId": { "type": "integer", "description": "The ID of the User Group the user must be part of or the ID of the Partner from which the user must have an invite from, for the set priority apply for the session." }, "type": { "type": "string", "enum": [ "partner", "userGroup" ] }, "priority": { "type": "number", "format": "float", "minimum": 0, "description": "The priority where 1 is equal to anyone else, 2 is twice as important, 0.5 is half as important." } } } } } }, "responses": { "200": { "description": "Circuit updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/configuration-templates/v1.0", "method": "GET", "operationId": "listConfigurationTemplates", "summary": "Configuration Template / Listing", "description": "Get all Configuration Templates", "tags": [ "resource / configuration templates" ], "parameters": { "query": { "filter": { "description": "Filters for OCPP version", "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "ocppVersion": { "type": "string", "enum": [ "ocpp1.6", "ocpp2.0.1" ], "description": "The OCPP version to filter by" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/configuration-templates/v1.0", "method": "POST", "operationId": "createConfigurationTemplate", "summary": "Configuration Template / Create", "description": "Create new Configuration Template", "tags": [ "resource / configuration templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "name": { "type": "string" }, "ocppVersion": { "type": "string", "enum": [ "ocpp 1.6", "ocpp 2.0.1" ] } }, "required": [ "name", "ocppVersion" ] } } } }, "responses": { "201": { "description": "Configuration Template created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "409": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/configuration-templates/v1.0/{template}", "method": "GET", "operationId": "getConfigurationTemplate", "summary": "Configuration Template / Read", "description": "Get Configuration Template", "tags": [ "resource / configuration templates" ], "responses": { "200": { "description": "Configuration Template returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/configuration-templates/v1.0/{template}", "method": "DELETE", "operationId": "deleteConfigurationTemplate", "summary": "Configuration Template / Delete", "description": "Delete Configuration Template", "tags": [ "resource / configuration templates" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/configuration-templates/v1.0/{template}", "method": "PATCH", "operationId": "updateConfigurationTemplate", "summary": "Configuration Template / Update", "description": "Update Configuration Template", "tags": [ "resource / configuration templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Configuration Template updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/configuration-templates/v1.0/{template}/variables", "method": "GET", "operationId": "configurationTemplateVariableListing", "summary": "Configuration Template Variable / Listing", "description": "Get all Configuration Template Variables", "tags": [ "resource / configuration templates" ], "parameters": { "path": { "template": { "type": "integer", "required": true } }, "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/configuration-templates/v1.0/{template}/variables", "method": "POST", "operationId": "configurationTemplateVariableCreate", "summary": "Configuration Template Variable / Create", "description": "Create a new Configuration Template Variable", "tags": [ "resource / configuration templates" ], "parameters": { "path": { "template": { "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "keyName": { "type": "string" }, "value": { "type": "string" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "keyName", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "integer" }, "value": { "type": "string" }, "variableName": { "type": "string" }, "variableType": { "type": "string", "enum": [ "Actual", "Target", "MinSet", "MaxSet" ], "nullable": true }, "variableInstance": { "type": "string", "nullable": true }, "component": { "type": "string" }, "componentInstance": { "type": "string", "nullable": true }, "evseId": { "type": "integer", "nullable": true }, "connectorId": { "type": "integer", "nullable": true }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "value", "variableName", "component" ], "additionalProperties": false, "description": "Represents a configuration variable based on the OCPP 2.0.1 specification. Fields such as `variableName`, `variableType`, `variableInstance`, `component`, `componentInstance`, `evseId`, and `connectorId` directly correspond to the OCPP 2.0.1 protocol." } ], "description": "Configuration template variable data for creation - OCPP 1.6 or 2.1" } } } }, "responses": { "201": { "description": "Configuration Template Key Variable successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/configuration-templates/v1.0/{template}/variables/{variable}", "method": "DELETE", "operationId": "configurationTemplateVariableDelete", "summary": "Configuration Template Variable / Delete", "description": "Delete a Configuration Template Variable", "tags": [ "resource / configuration templates" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/configuration-templates/v1.0/{template}/variables/{variable}", "method": "PATCH", "operationId": "configurationTemplateVariableUpdate", "summary": "Configuration Template Variable / Update", "description": "Update a Configuration Template Variable", "tags": [ "resource / configuration templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "keyName": { "type": "string" }, "value": { "type": "string" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "integer" }, "value": { "type": "string" }, "variableName": { "type": "string" }, "variableType": { "type": "string", "enum": [ "Actual", "Target", "MinSet", "MaxSet" ], "nullable": true }, "variableInstance": { "type": "string", "nullable": true }, "component": { "type": "string" }, "componentInstance": { "type": "string", "nullable": true }, "evseId": { "type": "integer", "nullable": true }, "connectorId": { "type": "integer", "nullable": true }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "additionalProperties": false, "description": "Represents a configuration variable based on the OCPP 2.0.1 specification. Fields such as `variableName`, `variableType`, `variableInstance`, `component`, `componentInstance`, `evseId`, and `connectorId` directly correspond to the OCPP 2.0.1 protocol." } ], "description": "Configuration template variable data for updates - OCPP 1.6 or 2.1" } } } }, "responses": { "200": { "description": "Configuration Template Variable updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/consent-history/v1.0", "method": "GET", "operationId": "consentHistoryListing", "summary": "Consent History / Listing", "description": "Retrieve the full consent history log showing all consent actions (agreements and rejections) performed by users over time. Results are ordered by actionAt descending (most recent first).", "tags": [ "resource / consent-history" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "userId": { "type": "array", "items": { "type": "integer" }, "description": "Filter consent history by specific user IDs" }, "termType": { "type": "array", "items": { "type": "string", "enum": [ "marketing", "signup", "subscription", "top-up" ] }, "description": "Filter by term types: - marketing: Marketing and promotional communications consent - signup: Initial registration terms and conditions - subscription: Subscription service terms - top-up: Top-up service terms" }, "action": { "type": "array", "items": { "type": "string", "enum": [ "agreed", "rejected" ] }, "description": "Filter by consent actions: - agreed: User agreed to the terms - rejected: User rejected the terms" }, "after": { "type": "string", "format": "date-time", "description": "Filter consent history entries where the action occurred after this date (ISO 8601 formatted datetime)" }, "before": { "type": "string", "format": "date-time", "description": "Filter consent history entries where the action occurred before this date (ISO 8601 formatted datetime)" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/consents/v1.0", "method": "GET", "operationId": "consentsListing", "summary": "Consents / Listing", "description": "Retrieve consent data for users", "tags": [ "resource / consents" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "userId": { "type": "array", "items": { "type": "integer" }, "description": "Filter consents by specific user IDs" }, "termType": { "type": "array", "items": { "type": "string", "enum": [ "marketing", "signup", "subscription", "top-up" ] }, "description": "Filter by term types: - marketing: Marketing and promotional communications consent - signup: Initial registration terms and conditions - subscription: Subscription service terms - top-up: Top-up service terms" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "agreed", "rejected" ] }, "description": "Filter by consent statuses: - agreed: User has agreed to the terms - rejected: User has explicitly rejected the terms" }, "agreedAfter": { "type": "string", "format": "date-time", "description": "Filter consents agreed after this date (ISO 8601 formatted date)" }, "agreedBefore": { "type": "string", "format": "date-time", "description": "Filter consents agreed before this date (ISO 8601 formatted date)" }, "rejectedAfter": { "type": "string", "format": "date-time", "description": "Filter consents rejected after this date (ISO 8601 formatted date)" }, "rejectedBefore": { "type": "string", "format": "date-time", "description": "Filter consents rejected before this date (ISO 8601 formatted date)" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/consents/v1.0", "method": "POST", "operationId": "consentsCreate", "summary": "Consents / Create", "description": "Create user consent for a specific term version. If a consent already exists for the given user and term version combination, the request will fail with a 409 Conflict error.", "tags": [ "resource / consents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "integer", "description": "The ID of the user for whom consent is being created" }, "termVersionId": { "type": "integer", "description": "The ID of the specific term version for which consent is being given or rejected" }, "status": { "type": "string", "enum": [ "agreed", "rejected" ], "example": "agreed", "description": "The consent status: - agreed: User has agreed to the terms - rejected: User has explicitly rejected the terms" } }, "required": [ "userId", "termVersionId", "status" ] } } } }, "responses": { "201": { "description": "Consent created successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/contact-details/v2.0", "method": "GET", "operationId": "contactDetailsRead", "summary": "Contact details / Read", "description": "Get the contact details", "tags": [ "resource / contact details" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/contact-details/v2.0", "method": "PUT", "operationId": "contactDetailsUpdate", "summary": "Contact details / Update", "description": "Update the contact details", "tags": [ "resource / contact details" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Contact details updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/contact-details/v2.0", "method": "DELETE", "operationId": "contactDetailsDelete", "summary": "Contact details / Delete", "description": "Delete contact details", "tags": [ "resource / contact details" ], "responses": { "204": { "description": "Contact details deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/cp-models/v1.0", "method": "GET", "operationId": "chargePointModelsListingDeprecated", "summary": "Charge Point Models / Listing", "description": "Get all Charge Point Models", "deprecated": true, "tags": [ "resource / charge point models" ], "parameters": { "query": { "page": { "description": "The page number to fetch (defaults to 1)", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "filter": { "schema": { "type": "object", "properties": { "vendorId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/cp-models/v1.0", "method": "POST", "operationId": "chargePointModelCreateDeprecated", "summary": "Charge Point Model / Create", "description": "Create new Charge Point Model", "deprecated": true, "tags": [ "resource / charge point models" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "vendorId": { "type": "integer" }, "userManual": { "type": "string", "format": "uri", "description": "A download link for the user manual. Shown in the mobile app for home chargers." }, "installerManual": { "type": "string", "format": "uri", "description": "URL to an externally-hosted installer manual. The system stores this URL reference only (does not download or cache the document) and provides it to installers for viewing/downloading through the installer app interface." } }, "required": [ "name", "vendorId" ] } } } }, "responses": { "201": { "description": "Charge Point Model created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/cp-models/v1.0/{modelId}", "method": "GET", "operationId": "chargePointModelReadDeprecated", "summary": "Charge Point Model / Read", "description": "Get a Charge Point Model", "deprecated": true, "tags": [ "resource / charge point models" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/cp-models/v1.0/{modelId}", "method": "DELETE", "operationId": "chargePointModelDeleteDeprecated", "summary": "Charge Point Model / Delete", "description": "Delete a Charge Point Model", "deprecated": true, "tags": [ "resource / charge point models" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/cp-models/v1.0/{modelId}", "method": "PATCH", "operationId": "chargePointModelUpdateDeprecated", "summary": "Charge Point Model / Update", "description": "Charge Point Model", "deprecated": true, "tags": [ "resource / charge point models" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "vendorId": { "type": "integer" }, "userManual": { "type": "string", "format": "uri", "description": "A download link for the user manual. Shown in the mobile app for home chargers." }, "installerManual": { "type": "string", "format": "uri", "description": "URL to an externally-hosted installer manual. The system stores this URL reference only (does not download or cache the document) and provides it to installers for viewing/downloading through the installer app interface." } } } } } }, "responses": { "200": { "description": "Charge Point Model updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/cp-vendors/v1.0", "method": "GET", "operationId": "chargePointVendorsListingDeprecated", "summary": "Charge Point Vendors / Listing", "description": "Get all Charge Point Vendors", "deprecated": true, "tags": [ "resource / charge point vendors" ], "parameters": { "query": { "page": { "description": "The page number to fetch (defaults to 1)", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/cp-vendors/v1.0", "method": "POST", "operationId": "chargePointVendorCreateDeprecated", "summary": "Charge Point Vendor / Create", "description": "Create new Charge Point Vendor", "deprecated": true, "tags": [ "resource / charge point vendors" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } } }, "responses": { "201": { "description": "Charge Point Vendor created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/cp-vendors/v1.0/{vendorId}", "method": "GET", "operationId": "chargePointVendorReadDeprecated", "summary": "Charge Point Vendor / Read", "description": "Get a Charge Point Vendor", "deprecated": true, "tags": [ "resource / charge point vendors" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/cp-vendors/v1.0/{vendorId}", "method": "DELETE", "operationId": "chargePointVendorDeleteDeprecated", "summary": "Charge Point Vendor / Delete", "description": "Delete a Charge Point Vendor", "deprecated": true, "tags": [ "resource / charge point vendors" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/cp-vendors/v1.0/{vendorId}", "method": "PATCH", "operationId": "chargePointVendorUpdateDeprecated", "summary": "Charge Point Vendor / Update", "description": "Charge Point Vendor", "deprecated": true, "tags": [ "resource / charge point vendors" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Charge Point Vendor updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/currencies/v2.0", "method": "GET", "operationId": "currenciesListing", "summary": "Currencies / Listing", "tags": [ "resource / currencies" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/currencies/v2.0", "method": "POST", "operationId": "currencyCreate", "summary": "Currency / Create", "description": "Create currency", "tags": [ "resource / currencies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alphabeticCode": { "type": "string", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "UYI", "UYU", "UYW", "UZS", "VES", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "XSU", "XTS", "XUA", "XXX", "YER", "ZAR", "ZMW", "ZWL" ], "description": "The currency 3-letter code." }, "prefix": { "type": "string", "nullable": true, "description": "When displaying amounts in this currency, the prefix is added in front of the amount. This could be symbols, for example $ or £." }, "suffix": { "type": "string", "nullable": true, "description": "When displaying amounts in this currency, the suffix is added after the amount." }, "decimal": { "type": "integer", "nullable": true, "description": "The actual precision of the currency. This is used when charging a payment method or calculating totals." }, "unitPriceAndCalculationsDecimal": { "type": "integer", "nullable": true, "description": "Used when setting price per kWh and per minute in tariffs." }, "enableUseOfMinorCurrencyUnit": { "type": "boolean", "description": "When enabled, the minor currency unit is used to set electricity price threshold for flexible tariffs and to set electricity cost tracking in the home charging app. The minor currency unit for the US dollar, for example, is the cent." }, "minorUnitSign": { "type": "string", "nullable": true, "description": "The sign or letter for the minor currency unit. For US dollar, for example, this could be \"¢\" or \"c\" for cents." } }, "required": [ "alphabeticCode" ] } } } }, "responses": { "201": { "description": "Currency created" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/currencies/v2.0/{currency}", "method": "GET", "operationId": "currencyRead", "summary": "Currency / Read", "tags": [ "resource / currencies" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/currencies/v2.0/{currency}", "method": "DELETE", "operationId": "currencyDeleteDeprecated", "summary": "Currency / Delete", "description": "Delete a currency", "deprecated": true, "tags": [ "resource / currencies" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/currencies/v2.0/{currency}", "method": "PATCH", "operationId": "currencyUpdate", "summary": "Currency / Update", "description": "Update a currency", "tags": [ "resource / currencies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alphabeticCode": { "type": "string", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "UYI", "UYU", "UYW", "UZS", "VES", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "XSU", "XTS", "XUA", "XXX", "YER", "ZAR", "ZMW", "ZWL" ], "description": "The currency 3-letter code." }, "prefix": { "type": "string", "nullable": true, "description": "When displaying amounts in this currency, the prefix is added in front of the amount. This could be symbols, for example $ or £." }, "suffix": { "type": "string", "nullable": true, "description": "When displaying amounts in this currency, the suffix is added after the amount." }, "decimal": { "type": "integer", "nullable": true, "description": "The actual precision of the currency. This is used when charging a payment method or calculating totals." }, "unitPriceAndCalculationsDecimal": { "type": "integer", "nullable": true, "description": "Used when setting price per kWh and per minute in tariffs." }, "enableUseOfMinorCurrencyUnit": { "type": "boolean", "description": "When enabled, the minor currency unit is used to set electricity price threshold for flexible tariffs and to set electricity cost tracking in the home charging app. The minor currency unit for the US dollar, for example, is the cent." }, "minorUnitSign": { "type": "string", "nullable": true, "description": "The sign or letter for the minor currency unit. For US dollar, for example, this could be \"¢\" or \"c\" for cents." } }, "required": [ "alphabeticCode" ] } } } }, "responses": { "200": { "description": "Currency updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/currency-rates/v1.0", "method": "GET", "operationId": "listCurrencyRates", "summary": "Currency Rate / Listing", "description": "Get all Currency Rates", "tags": [ "resource / currency rates" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "base": { "type": "string", "description": "Filter by base currency code" }, "target": { "type": "string", "description": "Filter by target currency code" }, "updatedBefore": { "type": "string", "format": "date-time", "description": "Filter by records updated before a specific datetime" }, "updatedAfter": { "type": "string", "format": "date-time", "description": "Filter by records updated after a specific datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/currency-rates/v1.0", "method": "POST", "operationId": "createCurrencyRate", "summary": "Currency Rate / Create", "description": "Create new Currency Rate", "tags": [ "resource / currency rates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base": { "type": "string", "example": "EUR", "description": "Base currency code (ISO 4217)" }, "target": { "type": "string", "example": "USD", "description": "Target currency code (ISO 4217)" }, "rate": { "type": "number", "format": "float", "example": 1.08, "description": "The exchange rate from base to target currency" } }, "required": [ "base", "target", "rate" ] } } } }, "responses": { "201": { "description": "Currency Rate created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/currency-rates/v1.0/{currencyRate}", "method": "GET", "operationId": "getCurrencyRate", "summary": "Currency Rate / Read", "description": "Get Currency Rate", "tags": [ "resource / currency rates" ], "responses": { "200": { "description": "Currency Rate returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/currency-rates/v1.0/{currencyRate}", "method": "DELETE", "operationId": "deleteCurrencyRate", "summary": "Currency Rate / Delete", "description": "Delete Currency Rate", "tags": [ "resource / currency rates" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/currency-rates/v1.0/{currencyRate}", "method": "PATCH", "operationId": "updateCurrencyRate", "summary": "Currency Rate / Update", "description": "Update Currency Rate", "tags": [ "resource / currency rates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rate": { "type": "number", "format": "float", "example": 1.08, "description": "The exchange rate from base to target currency" } }, "required": [ "rate" ] } } } }, "responses": { "200": { "description": "Currency Rate updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/custom-fees/v2.0", "method": "GET", "operationId": "customFeesListing", "summary": "Custom Fees / Listing", "description": "Get all custom fees", "tags": [ "resource / custom fees" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/custom-fees/v2.0/{customFee}", "method": "GET", "operationId": "customFeeRead", "summary": "Custom Fee / Read", "description": "Get a single custom fee", "tags": [ "resource / custom fees" ], "parameters": { "path": { "customFee": { "description": "The custom fee ID", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/downtime-period-notices/v1.0", "method": "GET", "operationId": "getDowntimePeriodNotices", "summary": "Downtime Period Notices / Listing", "description": "Get all Downtime Period Notices", "tags": [ "resource / downtime period notices" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "type": { "type": "string", "enum": [ "downtime", "exempt" ] } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/downtime-period-notices/v1.0", "method": "POST", "operationId": "postDowntimePeriodNotice", "summary": "Downtime Period Notices / Create", "description": "Create Downtime Period Notice", "tags": [ "resource / downtime period notices" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "type": { "type": "string", "enum": [ "downtime", "exempt" ] }, "notice": { "type": "string" }, "description": { "type": "string", "nullable": true } }, "required": [ "notice", "type" ] } } } }, "responses": { "201": { "description": "Downtime Period Notice successfully created" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/downtime-period-notices/v1.0/{notice}", "method": "GET", "operationId": "getDowntimePeriodNotice", "summary": "Downtime Period Notices / Read", "description": "Get Downtime Period Notice", "tags": [ "resource / downtime period notices" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/downtime-period-notices/v1.0/{notice}", "method": "DELETE", "operationId": "deleteDowntimePeriodNotice", "summary": "Downtime Period Notices / Delete", "description": "Delete Downtime Period Notice", "tags": [ "resource / downtime period notices" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/downtime-period-notices/v1.0/{notice}", "method": "PATCH", "operationId": "patchDowntimePeriodNotice", "summary": "Downtime Period Notices / Update", "description": "Update Downtime Period Notice", "tags": [ "resource / downtime period notices" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "downtime", "exempt" ] }, "notice": { "type": "string" }, "description": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-meters/v1.0", "method": "GET", "operationId": "electricityMetersLising", "summary": "Electricity Meters / Listing", "description": "Get all electricity meters", "tags": [ "resource / electricity meters" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the electricity meters that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the electricity meters that were last updated on and before this datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/electricity-meters/v1.0", "method": "POST", "operationId": "electricityMeterCreate", "summary": "Electricity Meter / Create", "description": "Create a new electricity meter", "tags": [ "resource / electricity meters" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "name": { "type": "string" }, "integrationId": { "type": "integer", "description": "The ID of an existing electricity meter integration." }, "integrationParameters": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "device_id": 123456 }, "description": "Electricity meter integration parameters." } }, "required": [ "name", "integrationId" ] } } } }, "responses": { "201": { "description": "Request succeeded" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-meters/v1.0/{electricityMeter}", "method": "GET", "operationId": "electricityMeterRead", "summary": "Electricity Meter / Read", "description": "Get information for an electricity meter by ID", "tags": [ "resource / electricity meters" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/electricity-meters/v1.0/{electricityMeter}", "method": "DELETE", "operationId": "electricityMeterDelete", "summary": "Electricity Meter / Delete", "description": "Delete an electricity meter.", "tags": [ "resource / electricity meters" ], "responses": { "204": { "description": "Electricity meter deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-meters/v1.0/{electricityMeter}", "method": "PATCH", "operationId": "electricityMeterUpdate", "summary": "Electricity Meter / Update", "description": "Update electricity meter", "tags": [ "resource / electricity meters" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "integrationId": { "type": "integer", "description": "The ID of an existing electricity meter integration." }, "integrationParameters": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "device_id": 123456 }, "description": "Electricity meter integration parameters." } } } } } }, "responses": { "200": { "description": "Electricity meter updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-rates/v1.0", "method": "GET", "operationId": "electricityRatesListingDeprecated", "summary": "Electricity rates / Listing", "description": "Get all Electricity rates", "deprecated": true, "tags": [ "resource / electricity rates" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "utilityId": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/electricity-rates/v1.0", "method": "POST", "operationId": "electricityRateCreateDeprecated", "summary": "Electricity rate / Create", "description": "Create a new Electricity rate", "deprecated": true, "tags": [ "resource / electricity rates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "utilityId": { "type": "integer", "nullable": true }, "pricingGranularityInMinutes": { "type": "integer", "enum": [ 60, 30, 15 ] }, "defaultPricePerKwh": { "type": "number", "description": "If there is no pricing supplied for a time interval or no time interval at all, this price would be used." }, "taxId": { "type": "integer", "description": "Deprecated! Please use `taxPercentage` instead! This field is used only to indicate the applied tax. All Electricity Rate prices should be supplied including the tax." }, "taxPercentage": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "example": 12.532, "description": "This field is used only to indicate the applied tax. All Electricity Rate prices should be supplied including the tax." }, "intervalPricing": { "type": "array", "items": { "type": "object", "properties": { "weekDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Specify the day for which the pricing would be valid." }, "elements": { "type": "array", "items": { "type": "object", "properties": { "startAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}$", "example": "00:00:00", "description": "Example 00:00:00" }, "endAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}$", "example": "01:00:00", "description": "Example 01:00:00" }, "price": { "type": "number", "nullable": true } }, "required": [ "startAt", "endAt" ] } } }, "required": [ "weekDays" ] }, "nullable": true, "description": "The time interval must be always the same for every single day through the week and could be either 15 min, 30 min or 60 min. The startAt and endAt must comply with this restriction." }, "intervalSpecialPricing": { "type": "array", "items": { "type": "object", "properties": { "specialPricingName": { "type": "string" }, "validOn": { "type": "array", "items": { "type": "string", "format": "date" }, "description": "A list of dates when the special pricing would apply, e.g. holidays, promo days, etc." }, "elements": { "type": "array", "items": { "type": "object", "properties": { "startAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}$", "example": "00:00:00", "description": "Example 00:00:00" }, "endAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}$", "example": "01:00:00", "description": "Example 01:00:00" }, "price": { "type": "number", "nullable": true } }, "required": [ "startAt", "endAt" ] } } }, "required": [ "specialPricingName", "validOn" ] }, "nullable": true, "description": "The same time interval as in intervalPricing must be used. The startAt and endAt must comply with this restriction." } }, "required": [ "id", "name", "pricingGranularityInMinutes", "defaultPricePerKwh" ] } } } }, "responses": { "201": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/electricity-rates/v1.0/{electricityRate}", "method": "GET", "operationId": "electricityRateReadDeprecated", "summary": "Electricity rate / Read", "description": "Get a single Electricity rate", "deprecated": true, "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/electricity-rates/v1.0/{electricityRate}", "method": "PUT", "operationId": "electricityRateUpdateDeprecated", "summary": "Electricity rate / Update", "description": "Update a Electricity rate. The update is rejected with 409 while another process is modifying the same rate; that conflict clears on its own and the request may be retried.", "deprecated": true, "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "utilityId": { "type": "integer", "nullable": true }, "pricingGranularityInMinutes": { "type": "integer", "enum": [ 60, 30, 15 ] }, "defaultPricePerKwh": { "type": "number", "description": "If there is no pricing supplied for a time interval or no time interval at all, this price would be used." }, "taxId": { "type": "integer", "description": "Deprecated! Please use `taxPercentage` instead! This field is used only to indicate the applied tax. All Electricity Rate prices should be supplied including the tax." }, "taxPercentage": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "example": 12.532, "description": "This field is used only to indicate the applied tax. All Electricity Rate prices should be supplied including the tax." }, "intervalPricing": { "type": "array", "items": { "type": "object", "properties": { "weekDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Specify the day for which the pricing would be valid." }, "elements": { "type": "array", "items": { "type": "object", "properties": { "startAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}$", "example": "00:00:00", "description": "Example 00:00:00" }, "endAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}$", "example": "01:00:00", "description": "Example 01:00:00" }, "price": { "type": "number", "nullable": true } }, "required": [ "startAt", "endAt" ] } } }, "required": [ "weekDays" ] }, "nullable": true, "description": "The time interval must be always the same for every single day through the week and could be either 15 min, 30 min or 60 min. The startAt and endAt must comply with this restriction." }, "intervalSpecialPricing": { "type": "array", "items": { "type": "object", "properties": { "specialPricingName": { "type": "string" }, "validOn": { "type": "array", "items": { "type": "string", "format": "date" }, "description": "A list of dates when the special pricing would apply, e.g. holidays, promo days, etc." }, "elements": { "type": "array", "items": { "type": "object", "properties": { "startAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}$", "example": "00:00:00", "description": "Example 00:00:00" }, "endAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}$", "example": "01:00:00", "description": "Example 01:00:00" }, "price": { "type": "number", "nullable": true } }, "required": [ "startAt", "endAt" ] } } }, "required": [ "specialPricingName", "validOn" ] }, "nullable": true, "description": "The same time interval as in intervalPricing must be used. The startAt and endAt must comply with this restriction." } }, "required": [ "id", "name", "pricingGranularityInMinutes", "defaultPricePerKwh" ] } ] } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-rates/v1.0/{electricityRate}", "method": "DELETE", "operationId": "electricityRateDeleteDeprecated", "summary": "Electricity rate / Delete", "description": "Delete a Electricity rate. Deletion is rejected with 409 while the rate is assigned to a charge point that has a reimbursement policy resolving the rate from the charge point. That conflict clears only when the configuration changes — either the policy is detached or the charge point is assigned another electricity rate; replacing the rate on the charge point is allowed.", "deprecated": true, "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true } } }, "responses": { "204": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." } } }, { "path": "/public-api/resources/electricity-rates/v2.0", "method": "GET", "operationId": "electricityRatesListing", "summary": "Electricity rates / Listing", "description": "Get all Electricity rates", "tags": [ "resource / electricity rates" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "utilityId": { "type": "integer" }, "type": { "type": "string", "enum": [ "admin_defined", "octopus_go", "agile_octopus", "nord_pool" ] } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/electricity-rates/v2.0", "method": "POST", "operationId": "electricityRateCreate", "summary": "Electricity rate / Create", "description": "Create a new Electricity rate", "tags": [ "resource / electricity rates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "name": { "type": "string" }, "utilityId": { "type": "integer", "nullable": true, "description": "The id of the utility providing the electricity. Configured in the admin panel." }, "defaultPrice": { "type": "number", "format": "decimal", "description": "The default price per kWh, which will be applied if there is no pricing supplied for a time interval. Prices of all electricity rates created through the Public API or the admin panel must include the tax in the price. Price per kWh." }, "taxPercentage": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "example": 12.532, "nullable": true, "description": "This field is used only to indicate the applied tax. All Electricity Rate prices should be provided with the tax included in the price." } }, "required": [ "name", "defaultPrice", "taxPercentage" ] } } } }, "responses": { "201": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}", "method": "GET", "operationId": "electricityRateRead", "summary": "Electricity rate / Read", "description": "Get a single Electricity rate", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}", "method": "DELETE", "operationId": "electricityRateDelete", "summary": "Electricity rate / Delete", "description": "Delete a Electricity rate. Deletion is rejected with 409 while the rate is assigned to a charge point that has a reimbursement policy resolving the rate from the charge point. That conflict clears only when the configuration changes — either the policy is detached or the charge point is assigned another electricity rate; replacing the rate on the charge point is allowed.", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true } } }, "responses": { "204": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}", "method": "PATCH", "operationId": "electricityRateUpdate", "summary": "Electricity rate / Update", "description": "Update a Electricity rate. The update is rejected with 409 while another process is modifying the same rate; that conflict clears on its own and the request may be retried.", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "utilityId": { "type": "integer", "nullable": true, "description": "The id of the utility providing the electricity. Configured in the admin panel." }, "defaultPrice": { "type": "number", "format": "decimal", "description": "The default price per kWh, which will be applied if there is no pricing supplied for a time interval. Prices of all electricity rates created through the Public API or the admin panel must include the tax in the price. Price per kWh." }, "taxPercentage": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "example": 12.532, "nullable": true, "description": "This field is used only to indicate the applied tax. All Electricity Rate prices should be provided with the tax included in the price." } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}/energy-mix", "method": "GET", "operationId": "electricityRateEnergyMixRead", "summary": "Electricity rate / Energy Mix / Read", "description": "Get an electricity rate energy mix", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}/energy-mix", "method": "PUT", "operationId": "electricityRateEnergyMixUpdate", "summary": "Electricity rate / Energy Mix / Update", "description": "Set an electricity rate energy mix. By default the energy mix generated with creation of the electricity rate is filled with 0.", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "solar": { "type": "number", "minimum": 0, "maximum": 100, "default": 0, "description": "Represents what percent of the energy is generated from solar power." }, "wind": { "type": "number", "minimum": 0, "maximum": 100, "default": 0, "description": "Represents what percent of the energy is generated from wind turbines." }, "hydro": { "type": "number", "minimum": 0, "maximum": 100, "default": 0, "description": "Represents what percent of the energy is generated from hydropower." }, "nuclear": { "type": "number", "minimum": 0, "maximum": 100, "default": 0, "description": "Represents what percent of the energy is generated from nuclear power plants." }, "coal": { "type": "number", "minimum": 0, "maximum": 100, "default": 0, "description": "Represents what percent of the energy is generated from burning coal." }, "naturalGas": { "type": "number", "minimum": 0, "maximum": 100, "default": 0, "description": "Represents what percent of the energy is generated from natural gas." }, "otherRenewable": { "type": "number", "minimum": 0, "maximum": 100, "default": 0, "description": "Represents what percent of the energy is generated from any other type of renewable energy source. This could include any other renewable source not specifically listed." }, "otherNonRenewable": { "type": "number", "minimum": 0, "maximum": 100, "default": 0, "description": "Represents what percent of the energy is generated from any other type of non-renewable energy source. This could include any other non-renewable source not specifically listed." } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}/price-periods", "method": "GET", "operationId": "electricityRatePricePeriodsListing", "summary": "Electricity rate / Price periods / Listing", "description": "List all of the configured price period days (including week days and dates)", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}/price-periods/date", "method": "GET", "operationId": "electricityRatePricePeriodsDateListing", "summary": "Electricity rate / Price periods / Date / Listing", "description": "List all of the configured price period dates", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}/price-periods/date/{date}", "method": "GET", "operationId": "electricityRatePricePeriodsDateRead", "summary": "Electricity rate / Price periods / Date / Read", "description": "Get the price periods for a specific date.", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true }, "date": { "type": "string", "format": "date", "example": "2024-10-28", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}/price-periods/date/{date}", "method": "PUT", "operationId": "electricityRatePricePeriodsDateCreateOrUpdate", "summary": "Electricity rate / Price periods / Date / Create or update", "description": "Update the price periods for a specific date. This operation will overwrite all existing periods for the given date, so a complete list must be provided", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true }, "date": { "type": "string", "format": "date", "example": "2024-10-28", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "periods": { "type": "array", "items": { "type": "object", "properties": { "startsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The start time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "endsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The end time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "price": { "type": "number", "format": "decimal", "example": 1.23, "description": "The price that will apply for the given price period. Must include tax." } }, "required": [ "startsAt", "endsAt", "price" ], "description": "A specific price period. The `startsAt` and `endsAt` times should be provided in the local time zone and not in UTC. Depending on the tenant multi timezone configuration either the tenant timezone will be used, or the timezone specific to the corresponding resource." } } }, "required": [ "periods" ] } } } }, "responses": { "200": { "description": "Date successfully updated" }, "201": { "description": "Date successfully created" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}/price-periods/date/{date}", "method": "DELETE", "operationId": "electricityRatePricePeriodsDateDelete", "summary": "Electricity rate / Price periods / Date / Delete", "description": "Delete the price periods for a specific date.", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true }, "date": { "type": "string", "format": "date", "example": "2024-10-28", "required": true } } }, "responses": { "204": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}/price-periods/week-day", "method": "GET", "operationId": "electricityRatePricePeriodsWeekDayListing", "summary": "Electricity rate / Price periods / Week day / Listing", "description": "List all of the configured price period week days", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}/price-periods/week-day/{weekDay}", "method": "GET", "operationId": "electricityRatePricePeriodsWeekDayRead", "summary": "Electricity rate / Price periods / Week day / Read", "description": "Get the price periods for a specific week day.", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true }, "weekDay": { "description": "The week day which is being requested, updated or deleted", "schema": { "type": "string", "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun", "any" ], "description": "Can be one of the listed days of the week or `any`." }, "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}/price-periods/week-day/{weekDay}", "method": "PUT", "operationId": "electricityRatePricePeriodsWeekDayCreateaOrUpdate", "summary": "Electricity rate / Price periods / Week day / Create or update", "description": "Update the price periods for a specific week day. This operation will overwrite all existing periods for the given day, so a complete list must be provided", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true }, "weekDay": { "description": "The week day which is being requested, updated or deleted", "schema": { "type": "string", "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun", "any" ], "description": "Can be one of the listed days of the week or `any`." }, "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "periods": { "type": "array", "items": { "type": "object", "properties": { "startsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The start time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "endsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The end time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "price": { "type": "number", "format": "decimal", "example": 1.23, "description": "The price that will apply for the given price period. Must include tax." } }, "required": [ "startsAt", "endsAt", "price" ], "description": "A specific price period. The `startsAt` and `endsAt` times should be provided in the local time zone and not in UTC. Depending on the tenant multi timezone configuration either the tenant timezone will be used, or the timezone specific to the corresponding resource." } } }, "required": [ "periods" ] } } } }, "responses": { "200": { "description": "Weekday successfully updated" }, "201": { "description": "Weekday successfully created" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/electricity-rates/v2.0/{electricityRate}/price-periods/week-day/{weekDay}", "method": "DELETE", "operationId": "electricityRatePricePeriodsWeekDayDelete", "summary": "Electricity rate / Price periods / Week day / Delete", "description": "Delete the price periods for a specific week day.", "tags": [ "resource / electricity rates" ], "parameters": { "path": { "electricityRate": { "description": "The ID of the electricity rate", "type": "integer", "required": true }, "weekDay": { "description": "The week day which is being requested, updated or deleted", "schema": { "type": "string", "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun", "any" ], "description": "Can be one of the listed days of the week or `any`." }, "required": true } } }, "responses": { "204": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/energy-coupon-templates/v1.0", "method": "GET", "operationId": "energyCouponTemplatesListing", "summary": "Energy coupon templates / Listing", "description": "Get all energy coupon templates with optional filtering", "tags": [ "resource / energy coupon templates" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused", "expired", "exhausted" ], "example": "active", "description": "Energy coupon template status: - **active**: Template is active and available for redemption - **paused**: Template is temporarily paused, no new redemptions allowed - **expired**: Template has been deactivated or reached its expiry date - **exhausted**: Template has reached its maximum number of redemptions" }, "code": { "type": "string", "description": "Filter by exact template code" }, "templateValidFrom": { "type": "string", "format": "date", "description": "Start of the period to filter by. Returns templates whose validity overlaps the period." }, "templateValidTo": { "type": "string", "format": "date", "description": "End of the period to filter by. Returns templates whose validity overlaps the period." }, "createdAfter": { "type": "string", "format": "date-time", "description": "Filter templates created after this timestamp (ISO 8601)" }, "createdBefore": { "type": "string", "format": "date-time", "description": "Filter templates created before this timestamp (ISO 8601)" }, "externalId": { "type": "string", "description": "Filter by external identifier" } }, "description": "Filters for energy coupon templates listing" } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/energy-coupon-templates/v1.0", "method": "POST", "operationId": "energyCouponTemplateCreate", "summary": "Energy coupon templates / Create", "description": "Create a new energy coupon template for promotional campaigns", "tags": [ "resource / energy coupon templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 50, "description": "Unique redemption code for the template" }, "name": { "type": "string", "maxLength": 255, "description": "Template name" }, "energyWh": { "type": "integer", "minimum": 1, "maximum": 4000000000, "description": "Energy amount in watt-hours granted per redemption" }, "maxRedemptionCount": { "type": "integer", "minimum": 0, "description": "Maximum number of redemptions allowed. Omitted means unlimited." }, "validityType": { "type": "string", "enum": [ "fixed_dates", "period" ], "example": "fixed_dates", "description": "Validity type for energy coupon templates: - **fixed_dates**: Coupons have fixed start and end dates - **period**: Coupons are valid for a number of days from the moment of redemption" }, "validityDurationDays": { "type": "integer", "minimum": 1, "description": "Number of days the coupon is valid from the moment of redemption. Required when validityType is period." }, "couponValidFrom": { "type": "string", "format": "date", "description": "Uses the YYYY-MM-DD date format." }, "couponValidTo": { "type": "string", "format": "date", "description": "Uses the YYYY-MM-DD date format." }, "templateValidFrom": { "type": "string", "format": "date", "description": "Uses the YYYY-MM-DD date format." }, "templateValidTo": { "type": "string", "format": "date", "description": "Uses the YYYY-MM-DD date format." }, "redemptionRules": { "type": "object", "properties": { "newUsersOnly": { "type": "boolean", "description": "When true, only users registered within the last 7 days can redeem. Does not limit redemption count — combine with `oncePerUser` to also limit new users to one redemption." }, "oncePerDevice": { "type": "boolean", "description": "When true, each device can redeem the template only once." }, "oncePerEmail": { "type": "boolean", "description": "When true, each email address can redeem the template only once." }, "oncePerPhoneNumber": { "type": "boolean", "description": "When true, each phone number can redeem the template only once." }, "oncePerUser": { "type": "boolean", "description": "When true, each user account can redeem the template only once." } }, "description": "Rules that restrict who can redeem this template. Each rule is an independent check; enabling multiple rules stacks them." }, "restrictions": { "type": "object", "properties": { "personalChargePointsOnly": { "type": "boolean", "description": "When true, coupons can only be used at personal (home) charge points." }, "evseType": { "type": "string", "enum": [ "ac", "dc", "any" ], "example": "any", "description": "EVSE type restriction for the energy coupon: - **ac**: Coupon can only be used at AC charging stations - **dc**: Coupon can only be used at DC charging stations - **any**: Coupon can be used at any charging station type" }, "countryRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "- **none**: No country restriction. - **allow**: Only countries in the list are allowed. - **deny**: Countries in the list are denied." }, "countries": { "type": "array", "items": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "description": "List of ISO 3166-1 alpha-2 country codes. Empty when type is none." } }, "required": [ "type" ], "description": "Allow/deny charge points in specific countries." }, "partnerRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny", "exclude_roaming" ], "description": "- **none**: No partner restriction. - **allow**: Only partners in the list are allowed. - **deny**: Partners in the list are denied. - **exclude_roaming**: Roaming charge points cannot be used. Partner list is ignored." }, "partnerIds": { "type": "array", "items": { "type": "integer" }, "description": "List of partner IDs. Empty when type is none or exclude_roaming." } }, "required": [ "type" ], "description": "Allow/deny charge points owned by specific partners, or exclude all roaming charge points." }, "locationRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "- **none**: No location restriction. - **allow**: Only locations in the list are allowed. - **deny**: Locations in the list are denied." }, "locationIds": { "type": "array", "items": { "type": "integer" }, "description": "List of location IDs. Empty when type is none." } }, "required": [ "type" ], "description": "Allow/deny specific locations." }, "locationTagRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "- **none**: No location tag restriction. - **allow**: Only locations with these tags are allowed. - **deny**: Locations with these tags are denied." }, "locationTagNames": { "type": "array", "items": { "type": "string" }, "description": "List of location tag names. Empty when type is none." } }, "required": [ "type" ], "description": "Allow/deny locations by tag name." }, "userGroupRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "- **none**: No user group restriction. - **allow**: Only users in these groups are allowed. - **deny**: Users in these groups are denied." }, "userGroupIds": { "type": "array", "items": { "type": "integer" }, "description": "List of user group IDs. Empty when type is none." } }, "required": [ "type" ], "description": "Allow/deny specific user groups." }, "minSessionEnergyWh": { "type": "integer", "minimum": 0, "description": "Minimum session energy in watt-hours required for the coupon to be applicable." }, "maxSessionEnergyWh": { "type": "integer", "minimum": 0, "description": "Maximum session energy in watt-hours for the coupon to be applicable." } }, "description": "Restrictions that limit where and by whom coupons can be used. All sub-restrictions are always returned." }, "externalId": { "type": "string", "maxLength": 255, "description": "An optional external identifier for integration purposes" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags associated with this template" }, "operatorId": { "type": "integer", "description": "Operator ID. Required for global admin tokens. Defaults to the token's operator for operator-scoped tokens." } }, "required": [ "code", "name", "energyWh", "validityType" ], "description": "Payload for creating an energy coupon template" } } } }, "responses": { "201": { "description": "Template created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "Conflict - A template with the same code already exists" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/energy-coupon-templates/v1.0/{energyCouponTemplate}", "method": "GET", "operationId": "energyCouponTemplateRead", "summary": "Energy coupon template / Read", "description": "Get a single energy coupon template by ID, including redemption statistics", "tags": [ "resource / energy coupon templates" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/energy-coupon-templates/v1.0/{energyCouponTemplate}", "method": "PATCH", "operationId": "energyCouponTemplateUpdate", "summary": "Energy coupon template / Update", "description": "Update an energy coupon template. Only non-structural fields can be updated.", "tags": [ "resource / energy coupon templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Template name" }, "maxRedemptionCount": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum number of redemptions allowed. Can only be increased or removed (unlimited). Cannot be decreased." }, "templateValidTo": { "type": "string", "format": "date", "description": "Uses the YYYY-MM-DD date format." }, "redemptionRules": { "type": "object", "properties": { "newUsersOnly": { "type": "boolean", "description": "When true, only users registered within the last 7 days can redeem. Does not limit redemption count — combine with `oncePerUser` to also limit new users to one redemption." }, "oncePerDevice": { "type": "boolean", "description": "When true, each device can redeem the template only once." }, "oncePerEmail": { "type": "boolean", "description": "When true, each email address can redeem the template only once." }, "oncePerPhoneNumber": { "type": "boolean", "description": "When true, each phone number can redeem the template only once." }, "oncePerUser": { "type": "boolean", "description": "When true, each user account can redeem the template only once." } }, "description": "Rules that restrict who can redeem this template. Each rule is an independent check; enabling multiple rules stacks them." }, "restrictions": { "type": "object", "properties": { "personalChargePointsOnly": { "type": "boolean", "description": "When true, coupons can only be used at personal (home) charge points." }, "evseType": { "type": "string", "enum": [ "ac", "dc", "any" ], "example": "any", "description": "EVSE type restriction for the energy coupon: - **ac**: Coupon can only be used at AC charging stations - **dc**: Coupon can only be used at DC charging stations - **any**: Coupon can be used at any charging station type" }, "countryRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "- **none**: No country restriction. - **allow**: Only countries in the list are allowed. - **deny**: Countries in the list are denied." }, "countries": { "type": "array", "items": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "description": "List of ISO 3166-1 alpha-2 country codes. Empty when type is none." } }, "required": [ "type" ], "description": "Allow/deny charge points in specific countries." }, "partnerRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny", "exclude_roaming" ], "description": "- **none**: No partner restriction. - **allow**: Only partners in the list are allowed. - **deny**: Partners in the list are denied. - **exclude_roaming**: Roaming charge points cannot be used. Partner list is ignored." }, "partnerIds": { "type": "array", "items": { "type": "integer" }, "description": "List of partner IDs. Empty when type is none or exclude_roaming." } }, "required": [ "type" ], "description": "Allow/deny charge points owned by specific partners, or exclude all roaming charge points." }, "locationRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "- **none**: No location restriction. - **allow**: Only locations in the list are allowed. - **deny**: Locations in the list are denied." }, "locationIds": { "type": "array", "items": { "type": "integer" }, "description": "List of location IDs. Empty when type is none." } }, "required": [ "type" ], "description": "Allow/deny specific locations." }, "locationTagRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "- **none**: No location tag restriction. - **allow**: Only locations with these tags are allowed. - **deny**: Locations with these tags are denied." }, "locationTagNames": { "type": "array", "items": { "type": "string" }, "description": "List of location tag names. Empty when type is none." } }, "required": [ "type" ], "description": "Allow/deny locations by tag name." }, "userGroupRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "- **none**: No user group restriction. - **allow**: Only users in these groups are allowed. - **deny**: Users in these groups are denied." }, "userGroupIds": { "type": "array", "items": { "type": "integer" }, "description": "List of user group IDs. Empty when type is none." } }, "required": [ "type" ], "description": "Allow/deny specific user groups." }, "minSessionEnergyWh": { "type": "integer", "minimum": 0, "description": "Minimum session energy in watt-hours required for the coupon to be applicable." }, "maxSessionEnergyWh": { "type": "integer", "minimum": 0, "description": "Maximum session energy in watt-hours for the coupon to be applicable." } }, "description": "Restrictions that limit where and by whom coupons can be used. All sub-restrictions are always returned." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags to associate with this template. Replaces existing tags." } } } } } }, "responses": { "200": { "description": "Template updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/energy-coupons/v1.0", "method": "GET", "operationId": "energyCouponsListing", "summary": "Energy coupons / Listing", "description": "Get all energy coupons", "tags": [ "resource / energy coupons" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "userId": { "type": "integer", "description": "Filter by user ID" }, "energyCouponTemplateId": { "type": "integer", "description": "Filter coupons that were created from a specific energy coupon template" }, "status": { "type": "string", "enum": [ "unredeemed", "inactive", "active", "locked", "fully_consumed", "expired", "cancelled" ], "example": "active", "description": "Energy coupon status: - **unredeemed**: Not yet assigned to a user - **inactive**: Waiting to become valid (valid from date is in the future) - **active**: Currently usable for charging sessions - **locked**: Locked by an ongoing charging session - **fully_consumed**: All energy has been consumed - **expired**: Validity period has passed - **cancelled**: Manually cancelled" }, "type": { "type": "string", "enum": [ "subscription", "support_grant", "manual_single", "promotional", "top_up_bonus" ], "example": "support_grant", "description": "Energy coupon type. Only `support_grant` and `manual_single` can be created via the API. The remaining types are created automatically by the system. - **subscription**: Automatically created from a subscription plan - **support_grant**: Created by an operator as a support grant - **manual_single**: Manually created single-use coupon - **promotional**: Created as part of a promotional campaign - **top_up_bonus**: Bonus coupon from a top-up" }, "createdAfter": { "type": "string", "format": "date-time" }, "createdBefore": { "type": "string", "format": "date-time" }, "externalId": { "type": "string", "description": "Filter by exact external ID match" } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/energy-coupons/v1.0", "method": "POST", "operationId": "energyCouponCreate", "summary": "Energy coupon / Create", "description": "Create a single-use energy coupon, optionally assigned to a specific user. When userId is omitted, the coupon is created with \"unredeemed\" status.", "tags": [ "resource / energy coupons" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "integer", "description": "The ID of the user to assign the coupon to. When omitted, the coupon is created without a user assignment (status will be \"unredeemed\")." }, "operatorId": { "type": "integer", "description": "Operator ID. Required for global admin tokens. Defaults to the token's operator for operator-scoped tokens." }, "energyWh": { "type": "integer", "minimum": 1, "maximum": 4000000000, "description": "Energy amount in watt-hours" }, "type": { "type": "string", "enum": [ "support_grant", "manual_single" ], "description": "Type of energy coupon to create. Only the following types can be created via the API: - **support_grant**: Created by an operator as a support grant - **manual_single**: Manually created single-use coupon" }, "evseType": { "type": "string", "enum": [ "ac", "dc", "any" ], "example": "any", "description": "EVSE type restriction for the energy coupon: - **ac**: Coupon can only be used at AC charging stations - **dc**: Coupon can only be used at DC charging stations - **any**: Coupon can be used at any charging station type" }, "validFrom": { "type": "string", "format": "date", "description": "Uses the YYYY-MM-DD date format." }, "validTo": { "type": "string", "format": "date", "description": "Uses the YYYY-MM-DD date format." }, "externalId": { "type": "string", "maxLength": 255, "description": "An optional external identifier for integration purposes" }, "restrictions": { "type": "object", "properties": { "personalChargePointsOnly": { "type": "boolean", "description": "When true, coupons can only be used at personal (home) charge points." }, "evseType": { "type": "string", "enum": [ "ac", "dc", "any" ], "example": "any", "description": "EVSE type restriction for the energy coupon: - **ac**: Coupon can only be used at AC charging stations - **dc**: Coupon can only be used at DC charging stations - **any**: Coupon can be used at any charging station type" }, "countryRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "- **none**: No country restriction. - **allow**: Only countries in the list are allowed. - **deny**: Countries in the list are denied." }, "countries": { "type": "array", "items": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "description": "List of ISO 3166-1 alpha-2 country codes. Empty when type is none." } }, "required": [ "type" ], "description": "Allow/deny charge points in specific countries." }, "partnerRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny", "exclude_roaming" ], "description": "- **none**: No partner restriction. - **allow**: Only partners in the list are allowed. - **deny**: Partners in the list are denied. - **exclude_roaming**: Roaming charge points cannot be used. Partner list is ignored." }, "partnerIds": { "type": "array", "items": { "type": "integer" }, "description": "List of partner IDs. Empty when type is none or exclude_roaming." } }, "required": [ "type" ], "description": "Allow/deny charge points owned by specific partners, or exclude all roaming charge points." }, "locationRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "- **none**: No location restriction. - **allow**: Only locations in the list are allowed. - **deny**: Locations in the list are denied." }, "locationIds": { "type": "array", "items": { "type": "integer" }, "description": "List of location IDs. Empty when type is none." } }, "required": [ "type" ], "description": "Allow/deny specific locations." }, "locationTagRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "- **none**: No location tag restriction. - **allow**: Only locations with these tags are allowed. - **deny**: Locations with these tags are denied." }, "locationTagNames": { "type": "array", "items": { "type": "string" }, "description": "List of location tag names. Empty when type is none." } }, "required": [ "type" ], "description": "Allow/deny locations by tag name." }, "userGroupRestriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "- **none**: No user group restriction. - **allow**: Only users in these groups are allowed. - **deny**: Users in these groups are denied." }, "userGroupIds": { "type": "array", "items": { "type": "integer" }, "description": "List of user group IDs. Empty when type is none." } }, "required": [ "type" ], "description": "Allow/deny specific user groups." }, "minSessionEnergyWh": { "type": "integer", "minimum": 0, "description": "Minimum session energy in watt-hours required for the coupon to be applicable." }, "maxSessionEnergyWh": { "type": "integer", "minimum": 0, "description": "Maximum session energy in watt-hours for the coupon to be applicable." } }, "description": "Restrictions that limit where and by whom coupons can be used. All sub-restrictions are always returned." } }, "required": [ "energyWh", "type" ] } } } }, "responses": { "201": { "description": "Energy coupon created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/energy-coupons/v1.0/{energyCoupon}", "method": "GET", "operationId": "energyCouponRead", "summary": "Energy coupon / Read", "description": "Get a single energy coupon with optional session data", "tags": [ "resource / energy coupons" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "energyCouponSessionConsumptions" ] }, "description": "Include additional information in the response. The following options are available:
- `energyCouponSessionConsumptions`: Include energy consumption records per charging session" } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/energy-coupons/v1.0/{energyCoupon}/energy-coupon-session-consumptions", "method": "GET", "operationId": "energyCouponSessionConsumptionRecords", "summary": "Energy coupon / Session consumption records", "description": "Returns a breakdown of how a coupon's energy was consumed across charging sessions. Each record represents the amount of energy drawn from this coupon by a specific session.", "tags": [ "resource / energy coupons" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evse-downtime-periods/v1.0", "method": "GET", "operationId": "evseDowntimePeriodsListing", "summary": "EVSE Downtime Periods / Listing", "description": "Get all EVSE Downtime Periods", "tags": [ "resource / evse downtime periods" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "evseId": { "type": "integer" }, "chargePointId": { "type": "integer", "description": "Filter the periods in which the evses belong to the charge point" }, "locationId": { "type": "integer" }, "entryMode": { "type": "string", "enum": [ "manual", "automatic" ] }, "type": { "type": "string", "enum": [ "downtime", "exempt" ] }, "startedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Resources with `startedAt >= startedAfter`." }, "stoppedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Resources with `stoppedAt <= stoppedBefore`." }, "durationLessThan": { "type": "integer", "description": "Resources with duration in minutes less than or equal given value." }, "durationGreaterThan": { "type": "integer", "description": "Resources with duration in minutes greater than or equal given value." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the specific resource that was last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the specific resource that was last updated on and before this datetime" } } } }, "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "statusLog" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/evse-downtime-periods/v1.0", "method": "POST", "operationId": "evseDowntimePeriodCreate", "summary": "EVSE Downtime Period / Create", "description": "Create Manual Exempt EVSE Downtime Period", "tags": [ "resource / evse downtime periods" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "evseId": { "type": "integer" }, "noticeId": { "type": "integer", "description": "Allowed only notice with `type = exempt`!" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time" } }, "required": [ "evseId", "noticeId", "startedAt", "endedAt" ] } } } }, "responses": { "201": { "description": "EVSE Downtime Period created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evse-downtime-periods/v1.0/{evseDowntimePeriod}", "method": "GET", "operationId": "evseDowntimePeriodRead", "summary": "EVSE Downtime Period / Read", "description": "Get EVSE Downtime Period", "tags": [ "resource / evse downtime periods" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "statusLog" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evse-downtime-periods/v1.0/{evseDowntimePeriod}", "method": "DELETE", "operationId": "evseDowntimePeriodDelete", "summary": "EVSE Downtime Period / Delete", "description": "Delete Manual Created EVSE Downtime Period", "tags": [ "resource / evse downtime periods" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evse-downtime-periods/v1.0/{evseDowntimePeriod}", "method": "PATCH", "operationId": "evseDowntimePeriodUpdate", "summary": "EVSE Downtime Period / Update", "description": "Update EVSE Downtime Period", "tags": [ "resource / evse downtime periods" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "noticeId": { "type": "integer", "nullable": true }, "startedAt": { "type": "string", "format": "date-time", "description": "Allowed only for downtime period with `type = exempt AND entryMode = manual`" }, "endedAt": { "type": "string", "format": "date-time", "description": "Allowed only for downtime period with `type = exempt AND entryMode = manual`" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evse-downtime-periods/v1.0/{evseDowntimePeriod}/status-log", "method": "GET", "operationId": "evseDowntimePeriodStatusLog", "summary": "EVSE Downtime Period / Status Log", "description": "Get the StatusLog entry that triggered this downtime period", "tags": [ "resource / evse downtime periods" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.0", "method": "GET", "operationId": "evsesListingDeprecated", "summary": "EVSEs / Listing", "description": "Get all EVSEs", "deprecated": true, "tags": [ "resource / evses" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "chargePointId": { "type": "string", "format": "integer", "description": "Only list EVSE on a certain charge point" }, "physicalReference": { "type": "string", "description": "Only list EVSE, identified by id (QR Code)" }, "evseStatus": { "type": "string", "enum": [ "active", "disabled", "out of order" ] }, "hardwareStatus": { "type": "string", "enum": [ "available", "preparing", "charging", "suspendedEV", "suspendedEVSE", "finishing", "reserved", "unavailable", "faulted" ], "description": "Only list EVSE with this hardware status" }, "evseType": { "type": "string", "enum": [ "ac", "dc" ], "description": "Only list EVSE with this type" }, "connectorId": { "type": "string", "format": "integer", "description": "Only list EVSE with this connector" }, "tariffGroupId": { "type": "string", "format": "integer", "description": "Only list EVSE with this tariff group" }, "partnerId": { "type": "string", "format": "integer", "description": "Only list EVSE with this partner" }, "roamingPlatformId": { "type": "string", "format": "integer", "description": "Only list EVSE with this roaming platform" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/evses/v2.0/{evse}", "method": "GET", "operationId": "evseReadDeprecated", "summary": "EVSE / Read", "description": "Get a EVSE", "deprecated": true, "tags": [ "resource / evses" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.0/{evse}", "method": "PUT", "operationId": "evseUpdateDeprecated", "summary": "EVSE / Update", "description": "Update a EVSE", "deprecated": true, "tags": [ "resource / evses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "chargePointId": { "type": "integer" }, "chargingProfile": { "type": "object", "nullable": true, "allOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "minChargingRate": { "type": "number", "nullable": true }, "schedulePeriods": { "type": "array", "items": { "type": "object", "properties": { "startPeriod": { "type": "integer" }, "limit": { "type": "number" }, "numberPhases": { "type": "integer" } } }, "nullable": true }, "scheduleStart": { "type": "string", "format": "datetime", "nullable": true }, "chargingRateUnit": { "type": "string", "enum": [ "A", "W" ] }, "stackLevel": { "type": "integer" }, "chargingProfileKind": { "type": "string", "enum": [ "Absolute", "Recurring", "Relative" ] }, "recurrencyKind": { "type": "string", "enum": [ "daily", "weekly" ], "nullable": true }, "chargingCompleteAt": { "type": "string", "format": "datetime", "nullable": true }, "purpose": { "type": "string", "enum": [ "ChargePointMaxProfile", "TxDefaultProfile", "TxProfile" ] }, "validTo": { "type": "string", "format": "datetime", "nullable": true }, "validFrom": { "type": "string", "format": "datetime", "nullable": true }, "duration": { "type": "integer", "nullable": true } } } ] }, "roaming": { "type": "object", "properties": { "evseId": { "type": "string", "nullable": true, "description": "The EVSE Id that we receive through roaming." }, "status": { "type": "string", "enum": [ "available", "blocked", "charging", "inoperative", "outoforder", "planned", "removed", "reserved", "unknown" ], "nullable": true, "description": "* `available` - The EVSE/Connector is able to start a new charging session. * `blocked` - The EVSE/Connector is not accessible because of a physical barrier, i.e. a car. * `charging` - The EVSE/Connector is in use. * `inoperative` - The EVSE/Connector is not yet active or it is no longer available (deleted). * `outoforder` - The EVSE/Connector is currently out of order. * `planned` - The EVSE/Connector is planned, will be operating soon. * `removed` - The EVSE/Connector/charge point is discontinued/removed. * `reserved` - The EVSE/Connector is reserved for a particular EV driver and is unavailable for other drivers. * `unknown` - No status information available. (Also used when offline)" }, "tariffIds": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "The tariffs IDS that we reveived from roaming (as were specified by the CPO)." } }, "nullable": true }, "connectors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "allOf": [ { "type": "string", "enum": [ "type1", "type2", "type3", "chademo", "ccs1", "ccs2", "catarc", "schuko", "nacs", "cee16", "cee32", "j1772", "inductive", "nema-5-20", "type-e-french", "type-g-british", "type-j-swiss", "avcon", "chaoji", "nema-6-30", "nema-6-50", "mcs", "unknown" ], "description": "Type of connector available on the EVSE: - **type1**: Type 1 connector (SAE J1772 AC) - **type2**: Type 2 connector (IEC 62196-2 AC) - **type3**: Type 3 connector (IEC 62196-2 AC) - **chademo**: CHAdeMO DC fast charging - **ccs1**: Combined Charging System 1 (CCS1/Combo 1) - **ccs2**: Combined Charging System 2 (CCS2/Combo 2) - **catarc**: CATARC connector (Chinese standard) - **schuko**: Standard European household socket - **nacs**: North American Charging Standard (Tesla) - **cee16**: CEE 16A industrial connector - **cee32**: CEE 32A industrial connector - **j1772**: SAE J1772 connector - **inductive**: Inductive/wireless charging - **nema-5-20**: Domestic M NEMA 5-20 Socket - **type-e-french**: French Type E socket - **type-g-british**: British Type G socket - **type-j-swiss**: Swiss Type J socket - **avcon**: AVCON connector (Australian standard) - **chaoji**: ChaoJi (CHAdeMO 3.0) - **nema-6-30**: NEMA 6-30 - **nema-6-50**: NEMA 6-50 - **mcs**: Megawatt Charging System (MCS) - **unknown**: Connector standard supplied by a 2.3.0+ OCPI roaming peer that is not part of the platform's recognised set. The original peer-supplied value is preserved internally and emitted on outbound OCPI flows." }, { "type": "string", "nullable": true } ] }, "format": { "type": "string", "enum": [ "socket", "cable" ], "nullable": true }, "status": { "type": "string", "enum": [ "active", "disabled" ], "nullable": true }, "ocpiMaxVoltage": { "type": "integer" }, "ocpiMaxAmperage": { "type": "integer" }, "ocpiMaxElectricPower": { "type": "integer" } } }, "nullable": true }, "physicalReference": { "type": "string", "description": "Unique identifier of the EVSE. QR code or EVSE ID for Roaming." }, "type": { "type": "string", "enum": [ "ac", "dc" ] }, "networkId": { "type": "string", "description": "The identifier of the EVSE within the station. Protocol specific. For OCPP use consecutive numbers starting from 1" }, "status": { "type": "string", "enum": [ "active", "disabled", "out of order" ] }, "tariffGroupId": { "type": "integer", "nullable": true, "description": "The ID of the tariff group attached to the EVSE. If the EVSE is not roaming and tariffGroupId is not specified, the default (free) tariff will be assigned. For roaming EVSEs the Tariff Group can only be updated if the option for manual management of EVSEs is enabled for the roaming CPO." }, "allowsReservation": { "type": "boolean", "description": "Indicates the evse capability of accepting reservations." }, "maxPowerKw": { "type": "number", "nullable": true, "description": "The max power displayed for the EVSE in the app. This value is NOT enforced, it is just to be displayed in the app." }, "maxVoltage": { "allOf": [ { "type": "string", "enum": [ "230", "380", "400", "480", "120", "208", "240", "110-130", "220-240", "277" ] }, { "description": "The maxVoltage of a CP can fluctuate. Hence, when creating a CP in the system the maxVoltage is given as a range. For OCPI purposes it maps as follows: * `220-240` = 230 * `110-130` = 120 * `400` = 400 * `380` = 380" } ] }, "maxAmperage": { "type": "number", "nullable": true }, "phases": { "type": "string", "enum": [ "single_phase", "three_phase" ], "nullable": true }, "phaseRotation": { "type": "string", "enum": [ "rst", "rts", "srt", "str", "trs", "tsr" ], "nullable": true }, "midMeterCertificationEndYear": { "type": "integer", "nullable": true, "description": "The mid meter certification end year." }, "externalId": { "type": "string", "nullable": true }, "notes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 123, "description": "Unique identifier for the note" }, "summary": { "type": "string", "maxLength": 255, "example": "Important maintenance note", "description": "Short summary or title of the note" }, "details": { "type": "string", "maxLength": 2000, "example": "This charge point requires monthly inspection due to high usage.", "description": "Detailed content of the note. Omitted when empty." }, "pinned": { "type": "boolean", "example": true, "description": "Whether the note is pinned (appears first in listings)" }, "createdByAdminId": { "type": "integer", "example": 1, "description": "ID of the admin who created the note. Omitted when unavailable." }, "updatedByAdminId": { "type": "integer", "example": 2, "description": "ID of the admin who last updated the note. Omitted when unavailable." }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-12-16T10:00:00Z", "description": "ISO-8601 timestamp when the note was created" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-12-16T12:00:00Z", "description": "ISO-8601 timestamp when the note was last updated" } }, "required": [ "id", "summary", "pinned", "createdAt", "updatedAt" ] }, "description": "If `include[]=notes` is provided with the request, the notes attached to this EVSE will be provided here. Notes are returned with pinned notes first, then ordered by creation date descending." }, "hardwareStatus": { "type": "string", "enum": [ "available", "preparing", "charging", "suspendedEV", "suspendedEVSE", "finishing", "reserved", "unavailable", "faulted", "occupied" ], "example": "suspendedEV", "nullable": true, "description": "EVSE hardware status: - **available**: EVSE is available for use - **preparing**: EVSE is preparing to charge (e.g., cable plugged in, awaiting authorization) - **charging**: EVSE is actively charging a vehicle - **suspendedEV**: Charging is suspended by the EV (vehicle-side pause) - **suspendedEVSE**: Charging is suspended by the EVSE (charger-side pause) - **finishing**: Charging session is finishing - **reserved**: EVSE is reserved - **unavailable**: EVSE is not available for use - **faulted**: EVSE is in a faulted state - **occupied**: EVSE is occupied" } }, "required": [ "physicalReference", "type", "maxVoltage", "phases", "networkId", "status", "allowsReservation" ] } } } }, "responses": { "200": { "description": "EVSE updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.0/{evse}/hardware-status-logs", "method": "GET", "operationId": "listEvseHardwareStatusLogs", "summary": "EVSE / Hardware Status Logs / Listing", "description": "Get paginated list of hardware status logs for an EVSE with optional status and date filtering", "tags": [ "resource / evses" ], "parameters": { "query": { "filter": { "description": "Filter options for EVSE hardware status logs", "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "preparing", "charging", "suspendedEV", "suspendedEVSE", "finishing", "reserved", "unavailable", "faulted", "occupied" ], "example": "suspendedEV", "description": "EVSE hardware status: - **available**: EVSE is available for use - **preparing**: EVSE is preparing to charge (e.g., cable plugged in, awaiting authorization) - **charging**: EVSE is actively charging a vehicle - **suspendedEV**: Charging is suspended by the EV (vehicle-side pause) - **suspendedEVSE**: Charging is suspended by the EVSE (charger-side pause) - **finishing**: Charging session is finishing - **reserved**: EVSE is reserved - **unavailable**: EVSE is not available for use - **faulted**: EVSE is in a faulted state - **occupied**: EVSE is occupied" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Only list status logs created after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Only list status logs created before this datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "List of hardware status logs returned successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.0/{evse}/latest-hardware-status-log", "method": "GET", "operationId": "getEvseLatestHardwareStatusLog", "summary": "EVSE / Latest Hardware Status Log", "description": "Get the latest hardware status log entry for an EVSE", "tags": [ "resource / evses" ], "responses": { "200": { "description": "Latest hardware status log returned successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.0/{evse}/notes", "method": "GET", "operationId": "evseNotesListing", "summary": "EVSE / Notes / Listing", "description": "List all notes for a specific EVSE. Notes are returned with pinned notes first, then ordered by creation date descending. **Required permission:** `Notes.view`", "tags": [ "resource / evses" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "pinned": { "type": "boolean", "example": true, "description": "Filter by pinned status" }, "createdAfter": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z", "description": "Filter notes created on or after this ISO-8601 datetime" }, "createdBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes created on or before this ISO-8601 datetime" }, "updatedAfter": { "type": "string", "format": "date-time", "example": "2025-12-01T00:00:00Z", "description": "Filter notes updated on or after this ISO-8601 datetime (useful for delta sync)" }, "updatedBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes updated on or before this ISO-8601 datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.0/{evse}/notes", "method": "POST", "operationId": "evseNoteCreate", "summary": "EVSE / Note / Create", "description": "Create a new note for a specific EVSE. **Required permission:** `Notes.create`", "tags": [ "resource / evses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Important maintenance note", "description": "Short summary or title of the note (required)" }, "details": { "type": "string", "maxLength": 2000, "example": "This charge point requires monthly inspection due to high usage.", "description": "Detailed content of the note (optional)" }, "pinned": { "type": "boolean", "default": false, "example": false, "description": "Whether the note should be pinned (optional, defaults to false)" } }, "required": [ "summary" ] } } } }, "responses": { "201": { "description": "Note created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.0/{evse}/notes/{note}", "method": "GET", "operationId": "evseNoteShow", "summary": "EVSE / Note / Read", "description": "Get a specific note for an EVSE. **Required permission:** `Notes.view`", "tags": [ "resource / evses" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.0/{evse}/notes/{note}", "method": "DELETE", "operationId": "evseNoteDelete", "summary": "EVSE / Note / Delete", "description": "Delete a specific note from an EVSE. Notes are permanently deleted (hard delete). **Required permission:** `Notes.delete`", "tags": [ "resource / evses" ], "responses": { "204": { "description": "Note deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.0/{evse}/notes/{note}", "method": "PATCH", "operationId": "evseNoteUpdate", "summary": "EVSE / Note / Update", "description": "Update a specific note for an EVSE. **Required permissions:** - `Notes.update` for updating summary and details - `Notes.pin` for updating the pinned field (in addition to Notes.update if other fields are included)", "tags": [ "resource / evses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Updated maintenance note", "description": "Short summary or title of the note" }, "details": { "type": "string", "maxLength": 2000, "example": "Updated inspection schedule.", "nullable": true, "description": "Detailed content of the note. Send null to clear." }, "pinned": { "type": "boolean", "example": true, "description": "Whether the note should be pinned. Requires Notes.pin permission." } } } } } }, "responses": { "200": { "description": "Note updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.1", "method": "GET", "operationId": "evsesListing", "summary": "EVSEs / Listing", "description": "Get all EVSEs", "tags": [ "resource / evses" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "chargePointId": { "type": "string", "format": "integer", "description": "Only list EVSEs on a certain charge point" }, "physicalReference": { "type": "string", "description": "Only list EVSEs, identified by id (QR Code)" }, "externalId": { "type": "string", "description": "Only list EVSEs, identified by externalId" }, "roaming": { "type": "boolean", "description": "If true, only roaming EVSEs will be returned. If false, only local EVSEs will be returned. If not passing, all EVSEs will be returned." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the specific resource that was last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the specific resource that was last updated on and before this datetime" }, "hasRoamingTariffIds": { "type": "boolean", "description": "If true, only EVSEs with non-empty roaming.tariffIds array will be returned. If false, only EVSEs without roaming.tariffIds (null, empty array, or no roaming record) will be returned." }, "hasTariffGroup": { "type": "boolean", "description": "If true, only EVSEs with a tariffGroupId will be returned. If false, only EVSEs without a tariffGroupId will be returned." }, "roamingOperatorIds": { "type": "array", "items": { "type": "integer" }, "description": "Array of roaming operator IDs. Only EVSEs belonging to one or more of the specified roaming operators will be returned." }, "parkingSpaceId": { "type": "integer", "description": "Filter EVSEs by associated parking space ID" }, "currentType": { "type": "string", "enum": [ "ac", "dc" ], "description": "Filter EVSEs by current type. If 'ac', only AC EVSEs will be returned. If 'dc', only DC EVSEs will be returned. If not provided, all EVSEs will be returned." } } } }, "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "chargingProfile", "connectors", "externalAppData", "notes" ] } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.1", "method": "POST", "operationId": "evseCreate", "summary": "EVSE / Create", "description": "Create new EVSE", "tags": [ "resource / evses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chargePointId": { "type": "integer", "description": "The ID of the charge point." }, "physicalReference": { "type": "string", "description": "The identifier that is presented to the users, so they can identify the EVSE at the location." }, "currentType": { "type": "string", "enum": [ "ac", "dc" ], "description": "Type of current available on the EVSE: - **ac**: Alternating Current (AC) charging - **dc**: Direct Current (DC) fast charging" }, "label": { "type": "string", "description": "The EVSE label will be exposed and visualized in the mobile application" }, "networkId": { "type": "string", "description": "The OCPP evse identifier (should be consecutive numbers starting from 1)" }, "status": { "type": "string", "enum": [ "enabled", "disabled", "out of order" ], "description": "For roaming EVSEs the status can only be updated if the option for manual management of EVSEs is enabled for the roaming CPO." }, "midMeterCertificationEndYear": { "type": "integer", "nullable": true, "description": "The mid meter certification end year." }, "tariffGroupId": { "type": "integer", "nullable": true, "description": "The ID of the tariff group attached to the EVSE. If the EVSE is not roaming and tariffGroupId is not specified, the default (free) tariff will be assigned. For roaming EVSEs the Tariff Group can only be updated if the option for manual management of EVSEs is enabled for the roaming CPO." }, "allowsReservation": { "type": "boolean", "description": "Manages whether reservations are allowed on this EVSE. Requires the Reservations to be activated for the system in order to enable for the EVSE." }, "bookingEnabled": { "type": "boolean", "description": "Indicates if the EVSE can be booked. Requires the Bookings to be activated for the operator and automatically enables allowsReservation when set to true." }, "monitoringEnabled": { "type": "boolean", "description": "When disabled, this EVSE will not be listed or counted in the Faults & connectivity loss widget or lens. The charge point will still appear for charge point-level faults (network loss, hardware faulted). Defaults to true." }, "powerOptions": { "type": "object", "properties": { "maxOutputVoltage": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Maximum output voltage for DC charging." }, "maxPower": { "type": "integer", "nullable": true, "description": "Maximum power of the EVSE in W (Watts)." }, "maxVoltage": { "type": "string", "enum": [ "230", "380", "400", "480", "120", "208", "240", "110-130", "220-240", "277" ], "nullable": true, "description": "The maximum intake (input) voltage of the EVSE. For the ac current type the output voltage is the same as this intake voltage, while for the dc current type the output voltage can differ and is exposed separately in maxOutputVoltage. The maxVoltage of a charge point can fluctuate. Hence, when creating a charge point in the system, the maxVoltage is given as a range. For OCPI purposes it maps as follows: 220-240 = 230 110-130 = 120 400 = 400 380 = 380" }, "maxAmperage": { "type": "number", "nullable": true }, "phases": { "type": "string", "enum": [ "single_phase", "three_phase", "split_phase" ], "nullable": true }, "phaseRotation": { "type": "string", "enum": [ "RST", "RTS", "SRT", "STR", "TRS", "TSR" ], "nullable": true, "description": "`R` stands for `L1`,
`S` - for `L2`
`T` - for `L3`
So for example `RST` = `L1`, `L2`, `L3`, while `RTS` = `L1`, `L3`, `L2`, etc.
We are deriving the connected phase from this property for single phase if connectedPhase is not provided. Please don't rely on this property anymore as this functionality will be turned of in near future. Pass the correct connectedPhase instead. If you pass both properties (connectedPhase and phaseRotation) only connectedPhase will be taken into consideration for determining the phase." }, "connectedPhase": { "type": "string", "enum": [ "L1", "L2", "L3", "L1_L2", "L1_L3", "L2_L3" ], "nullable": true, "description": "Specifies the active line conductors used in the circuit. - `L1_L2` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L2_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L2` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L3` - Valid when `phases` = `single_phase` in electrical configuration `star`" } } }, "externalId": { "type": "string" }, "capabilityOverrides": { "type": "object", "properties": { "rfidReader": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "creditCardPayable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "contactlessCardSupport": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "debitCardPayable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "chipCardSupport": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "pedTerminal": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "remoteStartStop": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "unlockCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "reservable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "chargingProfileCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "chargingPreferencesCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "startSessionConnectorRequired": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "tokenGroupCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" } }, "description": "Manual overrides for individual EVSE capabilities. Each property is independent. Send `force_enable` or `force_disable` to set or replace an override. Send `auto` to clear an existing override (the capability returns to automated detection). Omit a property to leave its current override unchanged." } }, "required": [ "chargePointId", "physicalReference", "currentType", "networkId", "status" ] } } } }, "responses": { "201": { "description": "EVSE created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.1/{evse}", "method": "GET", "operationId": "evseRead", "summary": "EVSE / Read", "description": "Get an EVSE", "tags": [ "resource / evses" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "chargingProfile", "connectors", "externalAppData", "notes", "accessibleParkingSpaces" ] } } } } }, "responses": { "200": { "description": "EVSE returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.1/{evse}", "method": "DELETE", "operationId": "evseDelete", "summary": "EVSE / Delete", "description": "Delete an EVSE", "tags": [ "resource / evses" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/evses/v2.1/{evse}", "method": "PATCH", "operationId": "evseUpdate", "summary": "EVSE / Update", "description": "Update an EVSE", "tags": [ "resource / evses" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "chargingProfile", "connectors", "externalAppData", "notes" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "physicalReference": { "type": "string", "description": "The identifier that is presented to the users, so they can identify the EVSE at the location." }, "currentType": { "type": "string", "enum": [ "ac", "dc" ], "description": "Type of current available on the EVSE: - **ac**: Alternating Current (AC) charging - **dc**: Direct Current (DC) fast charging" }, "label": { "type": "string", "description": "The EVSE label will be exposed and visualized in the mobile application" }, "networkId": { "type": "string", "description": "The OCPP evse identifier (should be consecutive numbers starting from 1)" }, "status": { "type": "string", "enum": [ "enabled", "disabled", "out of order" ], "description": "For roaming EVSEs the status can only be updated if the option for manual management of EVSEs is enabled for the roaming CPO." }, "midMeterCertificationEndYear": { "type": "integer", "nullable": true, "description": "The mid meter certification end year." }, "tariffGroupId": { "type": "integer", "nullable": true, "description": "The ID of the tariff group attached to the EVSE. If the EVSE is not roaming and tariffGroupId is not specified, the default (free) tariff will be assigned. For roaming EVSEs the Tariff Group can only be updated if the option for manual management of EVSEs is enabled for the roaming CPO." }, "allowsReservation": { "type": "boolean", "description": "Manages whether reservations are allowed on this EVSE. Requires the Reservations to be activated for the system in order to enable for the EVSE." }, "bookingEnabled": { "type": "boolean", "description": "Indicates if the EVSE can be booked. Requires the Bookings to be activated for the operator and automatically enables allowsReservation when set to true." }, "monitoringEnabled": { "type": "boolean", "description": "When disabled, this EVSE will not be listed or counted in the Faults & connectivity loss widget or lens. The charge point will still appear for charge point-level faults (network loss, hardware faulted). Defaults to true." }, "powerOptions": { "type": "object", "properties": { "maxOutputVoltage": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Maximum output voltage for DC charging." }, "maxPower": { "type": "integer", "nullable": true, "description": "Maximum power of the EVSE in W (Watts)." }, "maxVoltage": { "type": "string", "enum": [ "230", "380", "400", "480", "120", "208", "240", "110-130", "220-240", "277" ], "nullable": true, "description": "The maximum intake (input) voltage of the EVSE. For the ac current type the output voltage is the same as this intake voltage, while for the dc current type the output voltage can differ and is exposed separately in maxOutputVoltage. The maxVoltage of a charge point can fluctuate. Hence, when creating a charge point in the system, the maxVoltage is given as a range. For OCPI purposes it maps as follows: 220-240 = 230 110-130 = 120 400 = 400 380 = 380" }, "maxAmperage": { "type": "number", "nullable": true }, "phases": { "type": "string", "enum": [ "single_phase", "three_phase", "split_phase" ], "nullable": true }, "phaseRotation": { "type": "string", "enum": [ "RST", "RTS", "SRT", "STR", "TRS", "TSR" ], "nullable": true, "description": "`R` stands for `L1`,
`S` - for `L2`
`T` - for `L3`
So for example `RST` = `L1`, `L2`, `L3`, while `RTS` = `L1`, `L3`, `L2`, etc.
We are deriving the connected phase from this property for single phase if connectedPhase is not provided. Please don't rely on this property anymore as this functionality will be turned of in near future. Pass the correct connectedPhase instead. If you pass both properties (connectedPhase and phaseRotation) only connectedPhase will be taken into consideration for determining the phase." }, "connectedPhase": { "type": "string", "enum": [ "L1", "L2", "L3", "L1_L2", "L1_L3", "L2_L3" ], "nullable": true, "description": "Specifies the active line conductors used in the circuit. - `L1_L2` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L2_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1_L3` - Valid when `phases` = `split_phase` in electrical configuration `star` or `phases` = `single_phase` in electrical configuration `delta` - `L1` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L2` - Valid when `phases` = `single_phase` in electrical configuration `star` - `L3` - Valid when `phases` = `single_phase` in electrical configuration `star`" } } }, "externalId": { "type": "string" }, "capabilityOverrides": { "type": "object", "properties": { "rfidReader": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "creditCardPayable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "contactlessCardSupport": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "debitCardPayable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "chipCardSupport": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "pedTerminal": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "remoteStartStop": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "unlockCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "reservable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "chargingProfileCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "chargingPreferencesCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "startSessionConnectorRequired": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" }, "tokenGroupCapable": { "type": "string", "enum": [ "auto", "force_enable", "force_disable" ], "description": "Override value for an EVSE capability: - **auto**: Use automated detection logic (default) - **force_enable**: Always include this capability - **force_disable**: Never include this capability" } }, "description": "Manual overrides for individual EVSE capabilities. Each property is independent. Send `force_enable` or `force_disable` to set or replace an override. Send `auto` to clear an existing override (the capability returns to automated detection). Omit a property to leave its current override unchanged." } } } } } }, "responses": { "200": { "description": "EVSE updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/faqs/v2.0", "method": "GET", "operationId": "faqsListing", "summary": "FAQs / Listing", "description": "Get all FAQs", "tags": [ "resource / faqs" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/faqs/v2.0", "method": "POST", "operationId": "faqCreate", "summary": "FAQ / Create", "description": "Create new FAQ", "tags": [ "resource / faqs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "question": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "answer": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } } }, "required": [ "question", "answer" ] } } } }, "responses": { "201": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/faqs/v2.0/{faq}", "method": "GET", "operationId": "faqRead", "summary": "FAQ / Read", "description": "Get a FAQ", "tags": [ "resource / faqs" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/faqs/v2.0/{faq}", "method": "DELETE", "operationId": "faqDelete", "summary": "FAQ / Delete", "description": "Delete a FAQ", "tags": [ "resource / faqs" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/faqs/v2.0/{faq}", "method": "PATCH", "operationId": "faqUpdate", "summary": "FAQ / Update", "description": "FAQs", "tags": [ "resource / faqs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "answer": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/firmware-versions/v1.0", "method": "GET", "operationId": "firmwareVersionsListing", "summary": "Firmware Versions / Listing", "description": "Get all Firmware Versions", "tags": [ "resource / firmware versions" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "vendorId": { "type": "array", "items": { "type": "integer" }, "description": "Filter by charge point vendor IDs." }, "modelId": { "type": "array", "items": { "type": "integer" }, "description": "Filter by charge point model IDs." }, "firmwareVersion": { "type": "string", "description": "Filter by firmware version string. Matches both exact versions and versions that begin with the search string (e.g., \"1.2\" will match exactly \"1.2\" as well as versions like \"1.2.0\", \"1.2.3\", etc.)." } } } }, "include": { "description": "Include related resources. Use 'models' to include compatible charge point models.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "models" ] } } } } }, "responses": { "200": { "description": "Successfully retrieved the list of firmware versions" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/firmware-versions/v1.0/{firmwareVersion}", "method": "GET", "operationId": "firmwareVersionRead", "summary": "Firmware Version / Read", "description": "Get a Firmware Version", "tags": [ "resource / firmware versions" ], "parameters": { "query": { "include": { "description": "Include related resources. Use 'models' to include compatible charge point models.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "models" ] } } } } }, "responses": { "200": { "description": "Successfully retrieved the firmware version details" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/firmware-versions/v1.0/{firmwareVersion}/attached-models", "method": "GET", "operationId": "firmwareVersionAttachedModels", "summary": "Firmware Version / Attached Models", "description": "Get all charge point models attached to this firmware version", "tags": [ "resource / firmware versions" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Successfully retrieved the list of attached charge point models" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/flexibility-activation-requests/v1.0", "method": "GET", "operationId": "listFlexibilityActivationRequests", "summary": "Flexibility Activation Requests / Listing", "description": "Get a list of Flexibility Requests", "tags": [ "resource / flexibility activation requests" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "description": "Filter for the requests based on assetId", "schema": { "type": "object", "properties": { "assetId": { "type": "string", "description": "The ID of the Flexibility Asset to filter requests by" } } } } } }, "responses": { "200": { "description": "A list of Flexibility Activation Requests" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/flexibility-activation-requests/v1.0/{flexibilityActivationRequest}", "method": "GET", "operationId": "getFlexibilityActivationRequest", "summary": "Flexibility Activation Requests / Read", "description": "Get a flexibility activation request", "tags": [ "resource / flexibility activation requests" ], "responses": { "200": { "description": "Flexibility request returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/flexibility-assets/v1.0", "method": "GET", "operationId": "listFlexibilityAssets", "summary": "Flexibility Assets / Listing", "description": "Get a list of Flexibility Assets", "tags": [ "resource / flexibility assets" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "description": "Filters for the time range (updatedSince)", "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "updatedSince": { "type": "string", "format": "date-time", "description": "Filter for the assets updated since the given timestamp" } } } } } }, "responses": { "200": { "description": "A list of Flexibility Assets" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/flexibility-assets/v1.0", "method": "POST", "operationId": "createFlexibilityAsset", "summary": "Flexibility Assets / Create", "description": "Create new flexibility asset", "tags": [ "resource / flexibility assets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique ID of the Flexibility Asset." }, "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "dlmCircuitId": { "type": "number", "description": "ID of the DLM circuit." }, "description": { "type": "string", "nullable": true, "description": "Short description of the flexibility asset." }, "downwardRegulationLimit": { "type": "integer", "format": "int64", "description": "Downward regulation limit in Watts." }, "upwardRegulationLimit": { "type": "integer", "format": "int64", "description": "Upward regulation limit in Watts." }, "integrationId": { "type": "number", "description": "Flexibility integration." }, "integrationParameters": { "type": "object", "additionalProperties": true, "description": "Flexibility integration parameters." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "endsAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. If an end date is set the asset will be automatically disabled at that time. Historical time series and forecasts are not generated after the end date." } }, "required": [ "dlmCircuitId", "status", "integrationId" ] } } } }, "responses": { "201": { "description": "Flexibility asset created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/flexibility-assets/v1.0/{flexibilityAsset}", "method": "GET", "operationId": "getFlexibilityAsset", "summary": "Flexibility Assets / Read", "description": "Get a flexibility asset", "tags": [ "resource / flexibility assets" ], "responses": { "200": { "description": "Flexibility asset returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/flexibility-assets/v1.0/{flexibilityAsset}", "method": "DELETE", "operationId": "deleteFlexibilityAsset", "summary": "Flexibility Assets / Delete", "description": "Delete a flexibility asset", "tags": [ "resource / flexibility assets" ], "responses": { "204": { "description": "Flexibility asset deleted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/flexibility-assets/v1.0/{flexibilityAsset}", "method": "PATCH", "operationId": "updateFlexibilityAsset", "summary": "Flexibility Assets / Update", "description": "Update a flexibility asset. Changing the circuit will permanently delete all existing historical and forecast time series data and regenerate new data based on the selected circuit.", "tags": [ "resource / flexibility assets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique ID of the Flexibility Asset." }, "dlmCircuitId": { "type": "number", "description": "ID of the DLM circuit." }, "description": { "type": "string", "nullable": true, "description": "Short description of the flexibility asset." }, "downwardRegulationLimit": { "type": "integer", "format": "int64", "description": "Downward regulation limit in Watts." }, "upwardRegulationLimit": { "type": "integer", "format": "int64", "description": "Upward regulation limit in Watts." }, "integrationId": { "type": "number", "description": "Flexibility integration." }, "integrationParameters": { "type": "object", "additionalProperties": true, "description": "Flexibility integration parameters." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "endsAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. If an end date is set the asset will be automatically disabled at that time. Historical time series and forecasts are not generated after the end date." } } } } } }, "responses": { "200": { "description": "Flexibility Asset updated" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/flexibility-assets/v1.0/{flexibilityAsset}/historical-time-series", "method": "GET", "operationId": "getHistoricalTimeSeries", "summary": "Flexibility Assets / Historical Time Series", "description": "Get Historical Time Series for a Flexibility Asset", "tags": [ "resource / flexibility assets" ], "parameters": { "path": { "flexibilityAsset": { "description": "ID of the Flexibility Asset", "type": "integer", "required": true } }, "query": { "filter": { "description": "Filters for the time range (startTime and endTime)", "schema": { "type": "object", "properties": { "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Filtered list of Historical Time Series data" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/flexibility-assets/v1.0/{flexibilityAsset}/time-series-forecast", "method": "GET", "operationId": "getTimeSeriesForecast", "summary": "Flexibility Assets / Time Series Forecast", "description": "Get Time Series Forecast for a Flexibility Asset", "tags": [ "resource / flexibility assets" ], "parameters": { "path": { "flexibilityAsset": { "description": "ID of the Flexibility Asset", "type": "integer", "required": true } }, "query": { "filter": { "description": "Filters for the time range (startTime and endTime)", "schema": { "type": "object", "properties": { "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Filtered list of Time Series Forecast data" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/id-tags/v2.0", "method": "GET", "operationId": "idTagsListing", "summary": "Id Tags / Listing", "description": "Get all id tags", "tags": [ "resource / id tags" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "idTagUid": { "type": "string", "format": "integer", "description": "Only list Id tags with a certain UID" }, "idLabel": { "type": "string", "description": "Only list Id tags with a certain label" }, "userId": { "type": "string", "format": "integer", "description": "Only list Id tags with a certain user id" }, "expireAt": { "type": "string", "format": "date-time", "description": "Only list Id tags that have an expiration date grater or equal to the supplied date" }, "status": { "type": "string", "enum": [ "enabled", "disabled", "suspended" ], "description": "Only list Id tags in this status" }, "type": { "type": "string", "enum": [ "rfid", "mac_address", "emaid" ], "description": "Only list Id tags in this type" }, "rfidStandard": { "type": "string", "enum": [ "iso14443", "iso15693" ], "description": "RFID card standard." }, "isHomeChargingOnly": { "type": "string", "pattern": "^(true|false|1|0)?$", "description": "Filter by the home charging use only restriction: - `true` (or `1`) returns only ID tags restricted to home charging. - `false` (or `0`) returns only ID tags without the restriction. Omit the filter or send it with an empty value to return both." }, "partnerId": { "type": "string", "format": "integer", "nullable": true, "description": "Only list ID tags assigned to the specified Partner ID. Pass null to list ID tags without a Partner assigned." }, "vehicleId": { "type": "string", "format": "integer", "nullable": true, "description": "Only list ID tags currently associated with the specified vehicle ID. Pass null to list ID tags without a vehicle assigned." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the id tags that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the id tags that were last updated on and before this datetime" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/id-tags/v2.0", "method": "POST", "operationId": "idTagCreate", "summary": "Id Tag / Create", "description": "Create new Id Tag", "tags": [ "resource / id tags" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "id": { "type": "integer" }, "idTagUid": { "type": "string", "maxLength": 255, "example": 123456, "description": "Token used for authorization" }, "idLabel": { "type": "string", "nullable": true, "description": "Visual or other label that could be associated with the ID Tag. For ID tags that are shared with roaming partners, this value is sent as the OCPI visual_number. Values longer than 64 characters are not shared." }, "expireAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "enabled", "disabled", "suspended" ], "description": "The status of the ID tag. Use it to disable or suspend a tag * `enabled` The tag is enabled and is accepted as authentication method * `disabled` The tag is disabled by the admin user and is not acceptable as authorization method * `suspended` The tag is suspended by the owner of the tag and is not acceptable as authorization method" }, "type": { "type": "string", "enum": [ "rfid", "mac_address" ] }, "rfidStandard": { "type": "string", "enum": [ "iso14443", "iso15693" ], "description": "RFID card standard." }, "vehicleType": { "type": "string", "enum": [ null, "company_car", "private_car" ], "nullable": true, "description": "Marks how the ID tag is used. The value only applies when the ID tag has no associated vehicle; an ID tag associated with a vehicle takes the vehicle's usage type instead and this value has no effect. * `private_car` - suppresses company reimbursement for the home charging sessions of the ID tag. * `company_car` - does not suppress company reimbursement. It never makes a session eligible for reimbursement on its own; eligibility is still decided by the existing checks. * `null` - contributes no signal. The existing reimbursement classification decides the outcome unchanged. The reimbursement effect applies only where the home charging reimbursement feature is enabled; elsewhere the value is stored and returned but changes no reimbursement outcome." }, "isHomeChargingOnly": { "type": "boolean", "example": false, "description": "Restricts the ID tag to the holder's own home charge points, including charge points shared with the holder. The tag is not authorized anywhere else. Applicable to tags of type `rfid` only. Supplying this property on a create or update request for a tag of any other type is rejected with `422`. * **Read** - returned for RFID tags; omitted for all other tag types. * **Create** - optional. Defaults to `false` when omitted. * **Update** - optional. An omitted value preserves the current setting; send `false` to lift the restriction. There is no null value - `false` is the clear value." }, "paymentMethodId": { "type": "string", "nullable": true, "description": "Use `defaultPaymentOption` instead. The payment method that will be associated with the ID Tag. * For **credit/debit cards** the `paymentMethodId` should be provided * For **Corporate billing** - `corporate:{id}` * For **Subscription** - use `\"subscription\"` to use the user's active subscription * For **Auto selection** - use `\"auto\"` (recommended) or `null` (deprecated) * The \"last used\" concept has been replaced with \"auto\" selection which cycles through available payment methods." }, "defaultPaymentOption": { "type": "string", "example": "auto", "description": "The default payment option for this ID tag. Accepted values: * `auto` - Automated fallback sequence * A payment card ID - Specific registered payment card * `corporate:{id}` - Corporate billing account (replace {id} with the corporate billing ID) * `subscription` - User's active post-paid subscription At charging time, if the chosen payment option doesn't apply to the session (e.g., corporate billing not eligible for the charge point, subscription not applicable), the platform falls back to the user's other available payment methods." }, "userId": { "type": "integer", "nullable": true, "description": "Associate the ID tag with a user account. If the user is not presented, the tag will not be authorized! It makes sense to prepare the tags in advance, in case there is another process/entity is going to later assign them!" }, "externalId": { "type": "string", "nullable": true }, "partnerId": { "type": "integer", "nullable": false, "description": "The administrator accounts of the selected Partner will be able to edit and delete the specified ID tag" }, "vehicleId": { "type": "integer", "description": "Associate the ID tag with a vehicle." }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "idTagUid", "status", "type" ] } } } }, "responses": { "201": { "description": "Id Tag created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/id-tags/v2.0/{idTag}", "method": "GET", "operationId": "idTagRead", "summary": "Id Tag / Read", "description": "Get a Id Tag", "tags": [ "resource / id tags" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/id-tags/v2.0/{idTag}", "method": "DELETE", "operationId": "idTagDelete", "summary": "Id Tag / Delete", "description": "Delete a Id Tag", "tags": [ "resource / id tags" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/id-tags/v2.0/{idTag}", "method": "PATCH", "operationId": "idTagUpdate", "summary": "Id Tag / Update", "description": "Update a Id Tag", "tags": [ "resource / id tags" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "idTagUid": { "type": "string", "maxLength": 255, "example": 123456, "description": "Token used for authorization" }, "idLabel": { "type": "string", "nullable": true, "description": "Visual or other label that could be associated with the ID Tag. For ID tags that are shared with roaming partners, this value is sent as the OCPI visual_number. Values longer than 64 characters are not shared." }, "userLabel": { "type": "string", "description": "User-defined alias for the ID tag" }, "expireAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "enabled", "disabled", "suspended" ], "description": "The status of the ID tag. Use it to disable or suspend a tag * `enabled` The tag is enabled and is accepted as authentication method * `disabled` The tag is disabled by the admin user and is not acceptable as authorization method * `suspended` The tag is suspended by the owner of the tag and is not acceptable as authorization method" }, "type": { "type": "string", "enum": [ "rfid", "mac_address" ] }, "rfidStandard": { "type": "string", "enum": [ "iso14443", "iso15693" ], "nullable": true, "description": "RFID card standard." }, "vehicleType": { "type": "string", "enum": [ null, "company_car", "private_car" ], "nullable": true, "description": "Marks how the ID tag is used. The value only applies when the ID tag has no associated vehicle; an ID tag associated with a vehicle takes the vehicle's usage type instead and this value has no effect. * `private_car` - suppresses company reimbursement for the home charging sessions of the ID tag. * `company_car` - does not suppress company reimbursement. It never makes a session eligible for reimbursement on its own; eligibility is still decided by the existing checks. * `null` - contributes no signal. The existing reimbursement classification decides the outcome unchanged. The reimbursement effect applies only where the home charging reimbursement feature is enabled; elsewhere the value is stored and returned but changes no reimbursement outcome." }, "isHomeChargingOnly": { "type": "boolean", "example": false, "description": "Restricts the ID tag to the holder's own home charge points, including charge points shared with the holder. The tag is not authorized anywhere else. Applicable to tags of type `rfid` only. Supplying this property on a create or update request for a tag of any other type is rejected with `422`. * **Read** - returned for RFID tags; omitted for all other tag types. * **Create** - optional. Defaults to `false` when omitted. * **Update** - optional. An omitted value preserves the current setting; send `false` to lift the restriction. There is no null value - `false` is the clear value." }, "paymentMethodId": { "type": "string", "nullable": true, "description": "Use `defaultPaymentOption` instead. The payment method that will be associated with the ID Tag. * For **credit/debit cards** the `paymentMethodId` should be provided * For **Corporate billing** - `corporate:{id}` * For **Subscription** - use `\"subscription\"` to use the user's active subscription * For **Auto selection** - use `\"auto\"` (recommended) or `null` (deprecated) * The \"last used\" concept has been replaced with \"auto\" selection which cycles through available payment methods." }, "defaultPaymentOption": { "type": "string", "example": "auto", "description": "The default payment option for this ID tag. Accepted values: * `auto` - Automated fallback sequence * A payment card ID - Specific registered payment card * `corporate:{id}` - Corporate billing account (replace {id} with the corporate billing ID) * `subscription` - User's active post-paid subscription At charging time, if the chosen payment option doesn't apply to the session (e.g., corporate billing not eligible for the charge point, subscription not applicable), the platform falls back to the user's other available payment methods." }, "userId": { "type": "integer", "nullable": true, "description": "Associate the ID tag with a user account. If the user is not presented, the tag will not be authorized! It makes sense to prepare the tags in advance, in case there is another process/entity is going to later assign them!" }, "externalId": { "type": "string", "nullable": true }, "partnerId": { "type": "integer", "nullable": true, "description": "The administrator accounts of the selected Partner will be able to edit and delete the specified ID tag" }, "vehicleId": { "type": "integer", "nullable": true, "description": "Associate the ID tag with a vehicle." }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } } } } } }, "responses": { "200": { "description": "Id Tag updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/id-tags/v2.0/{idTag}/notes", "method": "GET", "operationId": "idTagNotesListing", "summary": "ID tag / Notes / Listing", "description": "List all notes for a specific ID tag. Notes are returned with pinned notes first, then ordered by ID descending. **Required permission:** `Notes.view`", "tags": [ "resource / id tags" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "pinned": { "type": "boolean", "example": true, "description": "Filter by pinned status" }, "createdAfter": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z", "description": "Filter notes created on or after this ISO-8601 datetime" }, "createdBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes created on or before this ISO-8601 datetime" }, "updatedAfter": { "type": "string", "format": "date-time", "example": "2025-12-01T00:00:00Z", "description": "Filter notes updated on or after this ISO-8601 datetime (useful for delta sync)" }, "updatedBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes updated on or before this ISO-8601 datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/id-tags/v2.0/{idTag}/notes", "method": "POST", "operationId": "idTagNoteCreate", "summary": "ID tag / Note / Create", "description": "Create a new note for a specific ID tag. **Required permission:** `Notes.create`", "tags": [ "resource / id tags" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Important maintenance note", "description": "Short summary or title of the note (required)" }, "details": { "type": "string", "maxLength": 2000, "example": "This charge point requires monthly inspection due to high usage.", "description": "Detailed content of the note (optional)" }, "pinned": { "type": "boolean", "default": false, "example": false, "description": "Whether the note should be pinned (optional, defaults to false)" } }, "required": [ "summary" ] } } } }, "responses": { "201": { "description": "Note created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/id-tags/v2.0/{idTag}/notes/{note}", "method": "GET", "operationId": "idTagNoteRead", "summary": "ID tag / Note / Read", "description": "Get a specific note for an ID tag. **Required permission:** `Notes.view`", "tags": [ "resource / id tags" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/id-tags/v2.0/{idTag}/notes/{note}", "method": "DELETE", "operationId": "idTagNoteDelete", "summary": "ID tag / Note / Delete", "description": "Delete a specific note from an ID tag. Notes are permanently deleted. **Required permission:** `Notes.delete`", "tags": [ "resource / id tags" ], "responses": { "204": { "description": "Note deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/id-tags/v2.0/{idTag}/notes/{note}", "method": "PATCH", "operationId": "idTagNoteUpdate", "summary": "ID tag / Note / Update", "description": "Update a specific note for an ID tag. **Required permissions:** - `Notes.update` for updating summary and details - `Notes.pin` for updating the pinned field (in addition to Notes.update if other fields are included)", "tags": [ "resource / id tags" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Updated maintenance note", "description": "Short summary or title of the note" }, "details": { "type": "string", "maxLength": 2000, "example": "Updated inspection schedule.", "nullable": true, "description": "Detailed content of the note. Send null to clear." }, "pinned": { "type": "boolean", "example": true, "description": "Whether the note should be pinned. Requires Notes.pin permission." } } } } } }, "responses": { "200": { "description": "Note updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/installation-and-maintenance-companies/v1.0", "method": "GET", "operationId": "getInstallationAndMaintenanceCompaniesList", "summary": "Installation And Maintenance Companies / Listing", "description": "Get all Installation And Maintenance Companies", "tags": [ "resource / installation and maintenance companies" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "externalId": { "type": "string", "description": "Filter by external identifier" }, "countryCode": { "type": "string", "description": "Filter by country code (ISO 3166-1 alpha-2)" }, "integrationId": { "type": "integer", "description": "**This filter is deprecated. New integrations should use the Installer app's automatic managed-company assignment instead of setting the filtered property manually.** Filter by Installer app integration ID" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "Lists the installation and maintenance companies that have been last updated after the specified date and time, please provide the value as an ISO 8601 formatted date" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "Lists the installation and maintenance companies that have been last updated before the specified date and time, please provide the value as an ISO 8601 formatted date" } } } }, "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "chargePointIds" ] } } }, "page": { "description": "The page number to fetch (defaults to 1)", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/installation-and-maintenance-companies/v1.0", "method": "POST", "operationId": "createInstallationAndMaintenanceCompany", "summary": "Installation And Maintenance Companies / Create", "description": "Create Installation And Maintenance Company", "tags": [ "resource / installation and maintenance companies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "businessName": { "type": "string", "maxLength": 255, "description": "The internal name/identifier (max 255 chars)" }, "integrationId": { "type": "integer", "nullable": true, "description": "**This property is deprecated. New integrations should use the Installer app's automatic managed-company assignment instead of setting this property manually.** The system ID of the Installer app integration. Send null to clear." }, "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "External system identifier (max 255 chars). Send null to clear." }, "companyName": { "type": "string", "maxLength": 255, "nullable": true, "description": "The legal/display name of the company (max 255 chars). Send null to clear." }, "countryCode": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW", null ], "nullable": true, "description": "ISO 3166-1 alpha-2 country code. Send null to clear." }, "city": { "type": "string", "maxLength": 255, "nullable": true, "description": "City name (max 255 chars). Send null to clear." }, "region": { "type": "string", "maxLength": 255, "nullable": true, "description": "Region/state/province name (max 255 chars). Send null to clear." }, "address": { "type": "string", "maxLength": 255, "nullable": true, "description": "Street address (max 255 chars). Send null to clear." }, "postCode": { "type": "string", "maxLength": 255, "nullable": true, "description": "Postal/ZIP code (max 255 chars). Send null to clear." }, "contactPerson": { "type": "string", "maxLength": 255, "nullable": true, "description": "Name of the primary contact person (max 255 chars). Send null to clear." }, "email": { "type": "string", "format": "email", "maxLength": 255, "nullable": true, "description": "Contact email address (max 255 chars, email format validation). Send null to clear." }, "phone": { "type": "string", "maxLength": 255, "nullable": true, "description": "Contact phone number (max 255 chars). Send null to clear." } }, "required": [ "businessName" ] } } } }, "responses": { "201": { "description": "Installation And Maintenance Company successfully created" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/installation-and-maintenance-companies/v1.0/{imCompany}", "method": "GET", "operationId": "getInstallationAndMaintenanceCompany", "summary": "Installation And Maintenance Companies / Read", "description": "Get Installation And Maintenance Company", "tags": [ "resource / installation and maintenance companies" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "chargePointIds" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/installation-and-maintenance-companies/v1.0/{imCompany}", "method": "DELETE", "operationId": "deleteInstallationAndMaintenanceCompany", "summary": "Installation And Maintenance Companies / Delete", "description": "Delete Installation And Maintenance Company", "tags": [ "resource / installation and maintenance companies" ], "responses": { "204": { "description": "Installation And Maintenance Company successfully deleted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/installation-and-maintenance-companies/v1.0/{imCompany}", "method": "PATCH", "operationId": "updateInstallationAndMaintenanceCompany", "summary": "Installation And Maintenance Companies / Update", "description": "Update Installation And Maintenance Company", "tags": [ "resource / installation and maintenance companies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "businessName": { "type": "string", "maxLength": 255, "description": "The internal name/identifier (max 255 chars)" }, "integrationId": { "type": "integer", "nullable": true, "description": "**This property is deprecated. New integrations should use the Installer app's automatic managed-company assignment instead of setting this property manually.** The system ID of the Installer app integration. Send null to clear." }, "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "External system identifier (max 255 chars). Send null to clear." }, "companyName": { "type": "string", "maxLength": 255, "nullable": true, "description": "The legal/display name of the company (max 255 chars). Send null to clear." }, "countryCode": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW", null ], "nullable": true, "description": "ISO 3166-1 alpha-2 country code. Send null to clear." }, "city": { "type": "string", "maxLength": 255, "nullable": true, "description": "City name (max 255 chars). Send null to clear." }, "region": { "type": "string", "maxLength": 255, "nullable": true, "description": "Region/state/province name (max 255 chars). Send null to clear." }, "address": { "type": "string", "maxLength": 255, "nullable": true, "description": "Street address (max 255 chars). Send null to clear." }, "postCode": { "type": "string", "maxLength": 255, "nullable": true, "description": "Postal/ZIP code (max 255 chars). Send null to clear." }, "contactPerson": { "type": "string", "maxLength": 255, "nullable": true, "description": "Name of the primary contact person (max 255 chars). Send null to clear." }, "email": { "type": "string", "format": "email", "maxLength": 255, "nullable": true, "description": "Contact email address (max 255 chars, email format validation). Send null to clear." }, "phone": { "type": "string", "maxLength": 255, "nullable": true, "description": "Contact phone number (max 255 chars). Send null to clear." } } } } } }, "responses": { "200": { "description": "Installation And Maintenance Company successfully updated" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/installer-jobs/v1.0", "method": "GET", "operationId": "getInstallerJobsList", "summary": "InstallerJobs / Listing", "description": "Get all Installer Jobs", "tags": [ "resource / installer jobs" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "installationAndMaintenanceCompanyId": { "type": "integer" }, "locationId": { "type": "integer" }, "chargePointId": { "type": "integer" }, "status": { "type": "string", "enum": [ "new", "in_progress", "completed", "failed" ], "description": "The status of the installer job" }, "installerAdminId": { "type": "integer" }, "createdAfter": { "type": "string", "format": "date-time", "description": "Lists the installer jobs that have been created after the specified date and time, please provide the value as an ISO 8601 formatted date" }, "createdBefore": { "type": "string", "format": "date-time", "description": "Lists the installer jobs that have been created before the specified date and time, please provide the value as an ISO 8601 formatted date" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "Lists the installer jobs that have been last updated after the specified date and time, please provide the value as an ISO 8601 formatted date" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "Lists the installer jobs that have been last updated before the specified date and time, please provide the value as an ISO 8601 formatted date" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/installer-jobs/v1.0", "method": "POST", "operationId": "createInstallerJob", "summary": "Installer Jobs / Create", "description": "Create Installer Job", "tags": [ "resource / installer jobs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installationAndMaintenanceCompanyId": { "type": "integer", "description": "The ID of the installation and maintenance company which the installer job is assigned to" }, "installerAdminId": { "type": "integer", "description": "The ID of the installer admin if such is assigned to the installer job, if passed pin will be ignored" }, "pin": { "type": "string", "minLength": 4, "maxLength": 12, "description": "The PIN of the installer job, it is used to verify access rights to execute the installer job, if passed and no installerAdminId is provided, the pin will be assigned to the installer job" }, "description": { "type": "string" } }, "required": [ "installationAndMaintenanceCompanyId", "description" ] } } } }, "responses": { "201": { "description": "Installer Job successfully created" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/installer-jobs/v1.0/{installerJob}", "method": "GET", "operationId": "getInstallerJob", "summary": "Installer Jobs / Read", "description": "Get Installer Job", "tags": [ "resource / installer jobs" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "chargePoints" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/installer-jobs/v1.0/{installerJob}", "method": "DELETE", "operationId": "deleteInstallerJob", "summary": "Installer Jobs / Delete", "description": "Delete Installer Job", "tags": [ "resource / installer jobs" ], "responses": { "204": { "description": "Installer Job successfully deleted" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/installer-jobs/v1.0/{installerJob}", "method": "PATCH", "operationId": "updateInstallerJob", "summary": "Installer Jobs / Update", "description": "Update Installer Job", "tags": [ "resource / installer jobs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installerAdminId": { "type": "integer", "description": "The ID of the installer admin if such is assigned to the installer job, if passed pin will be ignored" }, "pin": { "type": "string", "minLength": 4, "maxLength": 12, "description": "The PIN of the installer job, it is used to verify access rights to execute the installer job, if passed and no installerAdminId is provided, the pin will be assigned to the installer job" }, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "Installer Job successfully updated" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/invoices/v1.0", "method": "GET", "operationId": "invoicesListing", "summary": "Invoices / Listing", "description": "Get all invoices", "tags": [ "resource / invoices" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "issuedFrom": { "type": "string", "description": "Only list invoices issued after this time" }, "issuedTo": { "type": "string", "description": "Only list invoices issued before this time" }, "externalId": { "type": "string", "description": "Filter invoices by exact match of external ID" }, "paymentStatus": { "type": "array", "items": { "type": "string", "enum": [ "paid", "partially_paid", "pending" ] }, "description": "Filter invoices by payment status. Accepts multiple comma-separated values." }, "fiscalizationStatus": { "type": "array", "items": { "type": "string", "enum": [ "pending", "certified", "failed", "canceled" ], "example": "certified", "description": "Certification status of the invoice with its fiscalization integration. - **pending**: The fiscal document exists and has been accepted for certification, but the fiscal authority has not yet confirmed it. The document is not yet legally issued. - **certified**: The fiscal authority confirmed the document, which is legally issued. `referenceNumber` carries the reference the integration recorded for it. In rare cases a certified document has no recorded reference and `referenceNumber` is absent; this does not resolve on its own and requires operator intervention. A document whose revocation has been requested but not yet confirmed, or whose revocation was rejected, is still `certified` — it remains legally issued until the authority confirms the revocation, at which point it becomes `canceled`. - **failed**: Certification did not succeed. Retries are attempted a bounded number of times; a status that remains `failed` requires operator intervention. The fiscal document remains, but no legally issued document exists for it. - **canceled**: The document was certified and has since been revoked with the fiscal authority. This is distinct from `failed` — the document was legally issued at some point, and `referenceNumber` keeps the reference the integration had recorded for it." }, "description": "Filter invoices by the certification status of their fiscal document. Accepts multiple comma-separated values. Invoices with no fiscal document are excluded whenever this filter is applied." }, "partnerId": { "type": "string", "format": "integer", "description": "Only list invoices issued from a specific Partner" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/invoices/v1.0/{invoice}", "method": "GET", "operationId": "invoiceRead", "summary": "Invoice / Read", "tags": [ "resource / invoices" ], "parameters": { "path": { "invoice": { "description": "The invoice ID to fetch", "type": "string", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/invoices/v1.0/{invoice}/fiscalization-attempts", "method": "GET", "operationId": "invoiceFiscalizationAttemptsListing", "summary": "Invoice fiscalization attempts / Listing", "description": "Get the fiscalization attempts an invoice's integration publishes, newest first. Integrations that do not publish attempts return an empty list.", "tags": [ "resource / invoices" ], "parameters": { "path": { "invoice": { "description": "The invoice ID to fetch", "type": "string", "required": true } }, "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/invoices/v1.0/{invoice}/fiscalization-documents/download", "method": "GET", "operationId": "invoiceFiscalizationDocumentDownload", "summary": "Invoice fiscalization document / Download", "description": "Download one of the document formats the fiscal authority has made available for a fiscalized invoice. Do not construct this URL: follow a `fiscalization.documents[].downloadUrl` link from the invoice response, which already carries the `format`, `expires` and `signature` query parameters. A missing or tampered signature yields `403 Forbidden`. The link expires 24 hours after the invoice response that produced it, after which it yields `410 Gone`, so request the invoice again for a fresh link rather than storing one. The link is signed and carries its own authorisation — no bearer token is used. The document is fetched from the fiscal authority only when the link is followed, so a provider that cannot supply the format at that moment yields `424 Failed Dependency` rather than a server error.", "tags": [ "resource / invoices" ], "parameters": { "path": { "invoice": { "description": "The invoice ID to fetch", "type": "string", "required": true } }, "query": { "format": { "description": "The document format to download, matched verbatim against the formats the fiscal authority has made available for this fiscal document. Carried by the signed link; changing it invalidates the signature.", "type": "string", "required": true, "example": "application/pdf" }, "expires": { "description": "Unix timestamp at which the signed link stops being accepted, 24 hours after the invoice response that produced it. Carried by the signed link; changing it invalidates the signature. Once this moment has passed the endpoint answers `410 Gone`.", "type": "integer", "required": true, "example": 1789344000 }, "signature": { "description": "Signature authorising this link. Carried by the signed link and the only credential the endpoint accepts — no bearer token is required or used.", "type": "string", "required": true } } }, "responses": { "200": { "description": "Success. The document is streamed back as an attachment. The `Content-Type` is the media type the fiscal authority returned for the requested format and is provider-defined, so read it from the response rather than assuming one." }, "403": { "description": "The link carries no signature, or a signature that does not match the URL it is being followed on. The signature covers the full link, including its host, so a constructed or altered URL is rejected — follow the `fiscalization.documents[].downloadUrl` link from the invoice response exactly as it was issued." }, "404": { "description": "No invoice matches the link, the invoice carries no fiscal document, the invoice's fiscalization integration does not support downloading document formats, or the requested `format` is not one the fiscal authority has made available for it." }, "410": { "description": "The link has expired. Signed links stop being accepted 24 hours after the invoice response that produced them. Request the invoice again for a fresh link." }, "424": { "description": "The fiscal authority could not supply the requested format at this moment. The `message` property carries the reason the provider reported." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/issues/v1.0", "method": "GET", "operationId": "issuesListing", "summary": "Issues / Listing", "description": "Get all issues with optional filtering and pagination", "tags": [ "resource / issues" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "status": { "type": "string", "enum": [ "auto_recovery_in_progress", "information_collection_in_progress", "new", "investigating", "resolution_in_progress", "resolved", "wont_fix", "non_issue" ], "example": "investigating", "description": "Issue status: - **auto_recovery_in_progress**: Issue is in automatic recovery process (preparation state) - **information_collection_in_progress**: System is collecting diagnostic information (preparation state) - **new**: Issue has been reported and not yet investigated (open state) - **investigating**: Issue is currently being investigated (open state) - **resolution_in_progress**: Resolution actions are being applied (open state) - **resolved**: Issue has been resolved successfully (closed state) - **wont_fix**: Issue will not be fixed (closed state) - **non_issue**: Reported issue determined to not be an actual issue (closed state)" }, "workflowState": { "type": "string", "enum": [ "preparation", "open", "closed" ], "example": "open", "description": "Issue workflow state (derived from status): - **preparation**: System is performing automatic actions before manual intervention (auto-resolution statuses) - **open**: Issue requires attention or is being worked on (new, investigating, resolutionInProgress) - **closed**: Issue is no longer active (resolved, wontFix, nonIssue)" }, "category": { "type": "string", "enum": [ "network", "payments_billing", "product_offerings", "ev_driver_ux", "security", "reporting", "roaming", "other" ], "example": "network", "description": "Issue category: - **network**: Network connectivity or communication issues - **payments_billing**: Payment processing or billing-related issues - **product_offerings**: Issues with product features or tariff offerings - **ev_driver_ux**: EV driver user experience issues - **security**: Security-related concerns or incidents - **reporting**: Reporting or analytics issues - **roaming**: Roaming-related issues - **other**: Issues not covered by other categories" }, "severity": { "type": "string", "enum": [ "severe", "significant", "moderate", "low" ], "example": "significant", "description": "Issue severity level: - **severe**: Critical impact requiring immediate attention - **significant**: Major impact affecting important functionality - **moderate**: Moderate impact with workaround available - **low**: Minor impact with minimal effect on operations" }, "priority": { "type": "string", "enum": [ "highest", "high", "medium", "low" ], "example": "high", "description": "Issue priority level: - **highest**: Must be addressed immediately - **high**: Should be addressed as soon as possible - **medium**: Should be addressed in normal workflow - **low**: Can be addressed when convenient" }, "assigneeId": { "type": "integer", "description": "Filter by assigned admin user ID" }, "keyResourceType": { "type": "string", "enum": [ "charge-point", "location", "evse", "session", "integration", "roaming-cdr", "roaming-connection" ], "example": "charge-point", "description": "Type of resource associated with an issue. - **charge-point**: Charge point equipment - **location**: Charging location - **evse**: Electric Vehicle Supply Equipment (individual charging outlet) - **session**: Charging session - **integration**: Integration setting (e.g., third-party service configuration) - **roaming-cdr**: Roaming charge detail record - **roaming-connection**: Roaming connection Note: Additional types (user) may appear in responses for issues created by automated systems." }, "keyResourceId": { "type": "integer", "description": "Filter by key resource ID" }, "createdAfter": { "type": "string", "format": "date-time", "description": "Filter issues created after this timestamp (ISO 8601 format)" }, "createdBefore": { "type": "string", "format": "date-time", "description": "Filter issues created before this timestamp (ISO 8601 format)" }, "updatedAfter": { "type": "string", "format": "date-time", "description": "Filter issues updated after this timestamp (ISO 8601 format)" }, "updatedBefore": { "type": "string", "format": "date-time", "description": "Filter issues updated before this timestamp (ISO 8601 format)" } }, "description": "Filters for issues listing" } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/issues/v1.0", "method": "POST", "operationId": "issuesCreate", "summary": "Issues / Create", "description": "Create a new issue. Note - auto-resolution statuses (autoRecoveryInProgress, informationCollectionInProgress) cannot be set via API.", "tags": [ "resource / issues" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this issue. Optional for global admin tokens (defaults to creating a global issue if not provided). Ignored for operator-scoped tokens (uses the token's operator)." }, "title": { "type": "string", "maxLength": 255, "description": "Issue title" }, "description": { "type": "string", "nullable": true, "description": "Detailed issue description (HTML content)" }, "category": { "type": "string", "enum": [ "network", "payments_billing", "product_offerings", "ev_driver_ux", "security", "reporting", "roaming", "other" ], "example": "network", "description": "Issue category: - **network**: Network connectivity or communication issues - **payments_billing**: Payment processing or billing-related issues - **product_offerings**: Issues with product features or tariff offerings - **ev_driver_ux**: EV driver user experience issues - **security**: Security-related concerns or incidents - **reporting**: Reporting or analytics issues - **roaming**: Roaming-related issues - **other**: Issues not covered by other categories" }, "severity": { "type": "string", "enum": [ "severe", "significant", "moderate", "low" ], "example": "significant", "description": "Issue severity level: - **severe**: Critical impact requiring immediate attention - **significant**: Major impact affecting important functionality - **moderate**: Moderate impact with workaround available - **low**: Minor impact with minimal effect on operations" }, "priority": { "type": "string", "enum": [ "highest", "high", "medium", "low" ], "example": "high", "description": "Issue priority level: - **highest**: Must be addressed immediately - **high**: Should be addressed as soon as possible - **medium**: Should be addressed in normal workflow - **low**: Can be addressed when convenient" }, "status": { "type": "string", "enum": [ "auto_recovery_in_progress", "information_collection_in_progress", "new", "investigating", "resolution_in_progress", "resolved", "wont_fix", "non_issue" ], "default": "new", "example": "investigating", "description": "Issue status: - **auto_recovery_in_progress**: Issue is in automatic recovery process (preparation state) - **information_collection_in_progress**: System is collecting diagnostic information (preparation state) - **new**: Issue has been reported and not yet investigated (open state) - **investigating**: Issue is currently being investigated (open state) - **resolution_in_progress**: Resolution actions are being applied (open state) - **resolved**: Issue has been resolved successfully (closed state) - **wont_fix**: Issue will not be fixed (closed state) - **non_issue**: Reported issue determined to not be an actual issue (closed state)" }, "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "External system identifier (UUID format recommended)" }, "assigneeAdminId": { "type": "integer", "nullable": true, "description": "ID of the admin user to assign this issue to" }, "keyResource": { "type": "object", "properties": { "resourceType": { "type": "string", "enum": [ "charge-point", "location", "evse", "session" ], "example": "charge-point", "description": "Type of resource that can be set as the key resource (primary subject) when creating an issue. - **charge-point**: Charge point equipment - **location**: Charging location - **evse**: Electric Vehicle Supply Equipment (individual charging outlet) - **session**: Charging session" }, "id": { "type": "integer", "description": "ID of the referenced resource" } }, "required": [ "resourceType", "id" ], "nullable": true, "description": "Primary resource this issue is related to (e.g., charge point, location, or EVSE). Once set, this cannot be changed via update operations." } }, "required": [ "title", "description", "category", "severity", "priority" ], "description": "Payload for creating a new issue" } } } }, "responses": { "201": { "description": "Issue created successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/issues/v1.0/{issue}", "method": "GET", "operationId": "issueRead", "summary": "Issue / Read", "description": "Get information for a single issue by ID", "tags": [ "resource / issues" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "relatedResources" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/issues/v1.0/{issue}", "method": "DELETE", "operationId": "issueDelete", "summary": "Issue / Delete", "description": "Delete an issue", "tags": [ "resource / issues" ], "responses": { "204": { "description": "Issue deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/issues/v1.0/{issue}", "method": "PATCH", "operationId": "issueUpdate", "summary": "Issue / Update", "description": "Update an existing issue. Supports partial updates (PATCH semantics). Notes: - keyResource cannot be updated after creation - Cannot set auto-resolution statuses (autoRecoveryInProgress, informationCollectionInProgress) - When setting status to resolved, wontFix, or nonIssue, resolutionDetails is required", "tags": [ "resource / issues" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "description": "Issue title" }, "description": { "type": "string", "description": "Detailed issue description (HTML content)" }, "status": { "type": "string", "enum": [ "auto_recovery_in_progress", "information_collection_in_progress", "new", "investigating", "resolution_in_progress", "resolved", "wont_fix", "non_issue" ], "example": "investigating", "description": "Issue status: - **auto_recovery_in_progress**: Issue is in automatic recovery process (preparation state) - **information_collection_in_progress**: System is collecting diagnostic information (preparation state) - **new**: Issue has been reported and not yet investigated (open state) - **investigating**: Issue is currently being investigated (open state) - **resolution_in_progress**: Resolution actions are being applied (open state) - **resolved**: Issue has been resolved successfully (closed state) - **wont_fix**: Issue will not be fixed (closed state) - **non_issue**: Reported issue determined to not be an actual issue (closed state)" }, "category": { "type": "string", "enum": [ "network", "payments_billing", "product_offerings", "ev_driver_ux", "security", "reporting", "roaming", "other" ], "example": "network", "description": "Issue category: - **network**: Network connectivity or communication issues - **payments_billing**: Payment processing or billing-related issues - **product_offerings**: Issues with product features or tariff offerings - **ev_driver_ux**: EV driver user experience issues - **security**: Security-related concerns or incidents - **reporting**: Reporting or analytics issues - **roaming**: Roaming-related issues - **other**: Issues not covered by other categories" }, "severity": { "type": "string", "enum": [ "severe", "significant", "moderate", "low" ], "example": "significant", "description": "Issue severity level: - **severe**: Critical impact requiring immediate attention - **significant**: Major impact affecting important functionality - **moderate**: Moderate impact with workaround available - **low**: Minor impact with minimal effect on operations" }, "priority": { "type": "string", "enum": [ "highest", "high", "medium", "low" ], "example": "high", "description": "Issue priority level: - **highest**: Must be addressed immediately - **high**: Should be addressed as soon as possible - **medium**: Should be addressed in normal workflow - **low**: Can be addressed when convenient" }, "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "External system identifier (UUID format recommended). Set to null to clear." }, "assigneeAdminId": { "type": "integer", "nullable": true, "description": "ID of the admin user to assign this issue to. Set to null to unassign." }, "resolutionDetails": { "type": "string", "nullable": true, "description": "Details about how the issue was resolved or why it was closed. Required when status is set to resolved, wont_fix, or non_issue." } }, "description": "Payload for updating an existing issue (PATCH semantics - all fields optional)" } } } }, "responses": { "200": { "description": "Issue updated successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v1.0", "method": "GET", "operationId": "locationsListingDeprecated", "summary": "Locations / Listing", "description": "Get all locations", "deprecated": true, "tags": [ "resource / locations" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "postCode": { "type": "string", "description": "The location post code" }, "partnerId": { "type": "string", "nullable": true, "description": "To list Locations that have charge points of a specific Partner, use the ID of the Partner. To list locations that have only charge points that don't have a Partner assigned, use null" }, "country": { "type": "string", "description": "The location country" }, "status": { "type": "string", "description": "The location status" }, "externalId": { "type": "string", "nullable": true, "description": "The location external ID" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v1.0", "method": "POST", "operationId": "locationCreateDeprecated", "summary": "Location / Create", "description": "Create new location", "deprecated": true, "tags": [ "resource / locations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "public_charge_points": { "type": "integer", "description": "The number of the charge points in that location that are both public and active" }, "public_charge_points_ids": { "type": "array", "items": { "type": "integer" }, "description": "The ids of the charge points in that location that are both public and active" }, "name": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "description": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "detailed_description": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "additional_description": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "geoposition": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ] }, "address": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "post_code": { "type": "string" }, "region": { "anyOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "For cases when the country is US." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "For cases when the country is AU." }, { "type": "string", "description": "For cases when the country is not US or AU." } ] }, "city": { "type": "string" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "external_id": { "type": "string", "nullable": true, "description": "The field should have unique value" }, "timezone": { "type": "string", "nullable": true, "description": "A valid timezone in the form of Area/Location, required when `Allow Multiple Time Zones` option is turned on in the Timezone Setting." }, "location_image": { "type": "object", "properties": { "original": { "type": "string", "description": "URL to the original image" }, "thumbnail": { "type": "string", "description": "URL to a thumbnail image" }, "mimeType": { "type": "string" }, "category": { "type": "string", "enum": [ "charger", "entrance", "location", "network", "operator", "other", "owner" ], "description": "Category of an image associated with a location: - **charger**: Photo of the charging station or charger - **entrance**: Photo of the entrance to the location - **location**: Photo of the location overview - **network**: Logo of the network or operator group - **operator**: Logo of the operator - **other**: Other image - **owner**: Logo of the owner" } }, "required": [ "original", "mimeType" ], "nullable": true }, "images": { "type": "array", "items": { "type": "object", "properties": { "original": { "type": "string", "description": "URL to the original image" }, "thumbnail": { "type": "string", "description": "URL to a thumbnail image" }, "mimeType": { "type": "string" }, "category": { "type": "string", "enum": [ "charger", "entrance", "location", "network", "operator", "other", "owner" ], "description": "Category of an image associated with a location: - **charger**: Photo of the charging station or charger - **entrance**: Photo of the entrance to the location - **location**: Photo of the location overview - **network**: Logo of the network or operator group - **operator**: Logo of the operator - **other**: Other image - **owner**: Logo of the owner" } }, "required": [ "original", "mimeType" ] } }, "working_hours": { "type": "object", "properties": { "is_always_open": { "type": "boolean", "description": "Indicates that the location is always open for charging. If set to false, the `hours` field is required, otherwise it should be ignored." }, "stop_session_outside_working_hours": { "type": "boolean", "nullable": true, "description": "If a User has initiated a charging session during Working hours but it is already outside of the Working hours, the session will be terminated by the system. This is valid only for Users that are not included in one of the User Groups for which the Location is available 24/7." }, "hours": { "type": "object", "properties": { "monday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "tuesday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "wednesday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "thursday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "friday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "saturday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "sunday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" } }, "nullable": true, "description": "The times should be considered to be in the location/tenant timezone. If a day does not have any entries, it will be treated as closed for the whole day." }, "always_open_for_user_group_ids": { "type": "array", "items": { "type": "number" }, "example": [ 1, 2, 3 ], "nullable": true } }, "required": [ "is_always_open" ] }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "name", "geoposition", "post_code", "city", "country", "region" ] } } } }, "responses": { "201": { "description": "Location created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v1.0/{location}", "method": "GET", "operationId": "locationReadDeprecated", "summary": "Location / Read", "description": "Get a single location", "deprecated": true, "tags": [ "resource / locations" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v1.0/{location}", "method": "DELETE", "operationId": "locationDeleteDeprecated", "summary": "Location / Delete", "description": "Delete a location", "deprecated": true, "tags": [ "resource / locations" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v1.0/{location}", "method": "PATCH", "operationId": "locationUpdateDeprecated", "summary": "Location / Update", "description": "Update a location", "deprecated": true, "tags": [ "resource / locations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "public_charge_points": { "type": "integer", "description": "The number of the charge points in that location that are both public and active" }, "public_charge_points_ids": { "type": "array", "items": { "type": "integer" }, "description": "The ids of the charge points in that location that are both public and active" }, "name": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "description": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "detailed_description": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "additional_description": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "geoposition": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ] }, "address": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "post_code": { "type": "string" }, "region": { "anyOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "For cases when the country is US." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "For cases when the country is AU." }, { "type": "string", "description": "For cases when the country is not US or AU." } ] }, "city": { "type": "string" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "external_id": { "type": "string", "nullable": true, "description": "The field should have unique value" }, "timezone": { "type": "string", "nullable": true, "description": "A valid timezone in the form of Area/Location, required when `Allow Multiple Time Zones` option is turned on in the Timezone Setting." }, "location_image": { "type": "object", "properties": { "original": { "type": "string", "description": "URL to the original image" }, "thumbnail": { "type": "string", "description": "URL to a thumbnail image" }, "mimeType": { "type": "string" }, "category": { "type": "string", "enum": [ "charger", "entrance", "location", "network", "operator", "other", "owner" ], "description": "Category of an image associated with a location: - **charger**: Photo of the charging station or charger - **entrance**: Photo of the entrance to the location - **location**: Photo of the location overview - **network**: Logo of the network or operator group - **operator**: Logo of the operator - **other**: Other image - **owner**: Logo of the owner" } }, "required": [ "original", "mimeType" ], "nullable": true }, "images": { "type": "array", "items": { "type": "object", "properties": { "original": { "type": "string", "description": "URL to the original image" }, "thumbnail": { "type": "string", "description": "URL to a thumbnail image" }, "mimeType": { "type": "string" }, "category": { "type": "string", "enum": [ "charger", "entrance", "location", "network", "operator", "other", "owner" ], "description": "Category of an image associated with a location: - **charger**: Photo of the charging station or charger - **entrance**: Photo of the entrance to the location - **location**: Photo of the location overview - **network**: Logo of the network or operator group - **operator**: Logo of the operator - **other**: Other image - **owner**: Logo of the owner" } }, "required": [ "original", "mimeType" ] } }, "working_hours": { "type": "object", "properties": { "is_always_open": { "type": "boolean", "description": "Indicates that the location is always open for charging. If set to false, the `hours` field is required, otherwise it should be ignored." }, "stop_session_outside_working_hours": { "type": "boolean", "nullable": true, "description": "If a User has initiated a charging session during Working hours but it is already outside of the Working hours, the session will be terminated by the system. This is valid only for Users that are not included in one of the User Groups for which the Location is available 24/7." }, "hours": { "type": "object", "properties": { "monday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "tuesday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "wednesday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "thursday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "friday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "saturday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "sunday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" } }, "nullable": true, "description": "The times should be considered to be in the location/tenant timezone. If a day does not have any entries, it will be treated as closed for the whole day." }, "always_open_for_user_group_ids": { "type": "array", "items": { "type": "number" }, "example": [ 1, 2, 3 ], "nullable": true } }, "required": [ "is_always_open" ] }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } } } } } }, "responses": { "200": { "description": "Location and updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0", "method": "GET", "operationId": "locationsListing", "summary": "Locations / Listing", "description": "Get all locations", "tags": [ "resource / locations" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "state": { "anyOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "For cases when the country is US." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "For cases when the country is AU." }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" ], "description": "For cases when the country is CA." }, { "type": "string", "enum": [ "81", "84", "85", "67", "89", "71", "76", "95", "79" ], "description": "For cases when the country is UM." } ] }, "region": { "type": "string" }, "city": { "type": "string" }, "partnerId": { "type": "integer" }, "externalId": { "type": "string" }, "tag": { "type": "string", "description": "Only list Locations that have the specific tag assigned." }, "roaming": { "type": "boolean", "description": "When true - returns only roaming locations. When false - returns only local locations owned by the authenticated operator." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the locations that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the locations that were last updated on and before this datetime" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only locations that were created on and after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only locations that were created on and before this datetime" } } } }, "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "chargingZones", "externalAppData", "images", "locationImage", "locationPin", "notes", "partnerIds" ] } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0", "method": "POST", "operationId": "locationCreate", "summary": "Location / Create", "description": "Create a new location", "tags": [ "resource / locations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "externalId": { "type": "string", "nullable": true }, "name": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Deprecated." }, "description": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "shortDescription": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "additionalDescription": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "geoposition": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ] }, "address": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "The full address of the location" }, "streetAddress": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "The street address of the location" }, "city": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true, "description": "When country is not in US, AU, CA, UM or RO, you can provide the region" }, "state": { "anyOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "When the country is US." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "When the country is AU." }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" ], "description": "When the country is CA." }, { "type": "string", "enum": [ "81", "84", "85", "67", "89", "71", "76", "95", "79" ], "description": "When the country is UM." }, { "type": "string", "enum": [ "AB", "AR", "AG", "BC", "BH", "BN", "BT", "BV", "BR", "B", "BZ", "CL", "CS", "CT", "CV", "DB", "DJ", "GL", "GR", "GJ", "HR", "HD", "IL", "IS", "IF", "MM", "MH", "MS", "NT", "OT", "PH", "SM", "SJ", "SB", "SV", "TR", "TM", "TL", "VS", "VL", "VN" ], "description": "When the country is RO." } ], "description": "When the selected country is one of US, AU, CA, UM or RO" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "postCode": { "type": "string", "nullable": true, "description": "Postal code of the location. Required for most countries — omitting it for those will result in a validation error." }, "timezone": { "type": "string", "nullable": true, "description": "A valid timezone in the form of Area/Location, required when `Allow Multiple Time Zones` option is turned on in the Timezone Setting." }, "parkingType": { "type": "string", "enum": [ "ALONG_MOTORWAY", "PARKING_GARAGE", "PARKING_LOT", "ON_DRIVEWAY", "ON_STREET", "UNDERGROUND_GARAGE", "IS_TENT", "SECURE" ], "nullable": true, "description": "Indicates the type of parking available at the charging location. This field helps EV drivers understand the physical parking environment before arrival. **Valid values:** - `ALONG_MOTORWAY` - Located along a motorway/highway, typically at rest areas or service stations - `PARKING_GARAGE` - Multi-level parking garage structure, either above-ground or mixed-use - `PARKING_LOT` - Surface parking lot, open-air parking area - `ON_DRIVEWAY` - Located on a private driveway, typically residential or small business - `ON_STREET` - Street-side parking, curbside charging locations - `UNDERGROUND_GARAGE` - Underground parking structure, subterranean parking facility - `IS_TENT` - Site located on the Trans-European Transport Network (Lithuania NAP / Via Lietuva extension; may not be interpreted by all roaming partners) - `SECURE` - Restricted-access parking such as gated lots, key-card access, or staffed parking (Lithuania NAP / Via Lietuva extension; may not be interpreted by all roaming partners) **Request behavior (POST/PATCH):** - Optional field when creating or updating locations - Send `null` to clear the parking type - Omit the field in PATCH requests to leave the existing value unchanged **Response behavior (GET):** - Field is omitted from the response when no parking type is configured (null in database) - When present, returns one of the valid enum values listed above" }, "accessibilityType": { "type": "string", "enum": [ "free_publicly_accessible", "restricted_access", "paid_publicly_accessible" ], "description": "Determines how the accessibility of the location is reported to OICP (Hubject) roaming partners. - `free_publicly_accessible` - The charge point is reachable without a fee - `restricted_access` - Permission is required to reach the charge point (e.g. company or building complex) - `paid_publicly_accessible` - A fee is required to reach the charge point (e.g. a paid parking garage)" }, "accessMethods": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "TOKEN", "LICENSE_PLATE", "ACCESS_CODE", "INTERCOM", "PARKING_TICKET" ] }, "example": [ "OPEN", "TOKEN" ], "nullable": true, "description": "Physical access methods available at this location. Multiple methods can be selected if the site supports different access types. **Request behavior (POST/PATCH):** - Optional field when creating or updating locations - Send `null` to clear all access methods - Send `[]` to store an empty access methods list - Duplicate values are automatically de-duplicated before storage - Omit the field in PATCH requests to leave the existing value unchanged **Response behavior (GET):** - Field is omitted from the response when no access methods are configured (null in database) - When access methods are configured but the array is empty, returns an empty array `[]` - When present, returns an array of valid enum values listed above **Available methods:** - `OPEN` - Publicly accessible without restrictions - `TOKEN` - Access via RFID token or card - `LICENSE_PLATE` - Access via license plate recognition - `ACCESS_CODE` - Access via PIN/access code entry - `INTERCOM` - Access via intercom system - `PARKING_TICKET` - Access via parking ticket validation" }, "facilities": { "type": "array", "items": { "type": "string", "enum": [ "AIRPORT", "BATHROOM", "BIKE_SHARING", "BUS_STOP", "CAFE", "CARPOOL_PARKING", "FUEL_STATION", "HOTEL", "MALL", "METRO_STATION", "MUSEUM", "NATURE", "PARKING_LOT", "RECREATION_AREA", "RESTAURANT", "SPORT", "STAFFED", "SUPERMARKET", "TAXI_STAND", "TRAIN_STATION", "TRAM_STOP", "WIFI" ] }, "nullable": true, "description": "Describes amenities and facilities available at or near the charging location. Most values are self-explanatory. Special categories include: - `RECREATION_AREA` - Parks, playgrounds, or leisure facilities - `CARPOOL_PARKING` - Dedicated parking for carpooling/ridesharing - `NATURE` - Natural attractions or green spaces - `STAFFED` - Location has staff present - `BATHROOM` - Bathroom facilities available **Request behavior (POST/PATCH):** - Optional field when creating or updating locations - Send `null` to clear all facilities - Send `[]` to store an empty facilities list - Duplicate values are automatically de-duplicated before storage - Omit the field in PATCH requests to leave the existing value unchanged **Response behavior (GET):** - Field is omitted from the response when no facilities are configured (null in database) - When facilities are configured but the array is empty, returns an empty array `[]` - When present, returns an array of valid enum values listed above" }, "paymentOptions": { "type": "array", "items": { "type": "string", "enum": [ "EMV_CHIP_TERMINAL", "NFC_CONTACTLESS_TERMINAL", "QR_CODE_PAYMENT", "WEB_PAYMENT", "CASH_PAYMENT" ], "description": "Payment methods accepted at the charging location, as required by AFIR (Alternative Fuels Infrastructure Regulation) for regulatory reporting. - `EMV_CHIP_TERMINAL` - EMV chip card terminal (contact-based card payments) - `NFC_CONTACTLESS_TERMINAL` - NFC contactless payment terminal (tap-to-pay) - `QR_CODE_PAYMENT` - QR code-based payment - `WEB_PAYMENT` - Web-based payment (e.g., browser or app payment flow) - `CASH_PAYMENT` - Cash payment accepted" }, "nullable": true, "description": "Payment methods accepted at the charging location, as required by AFIR (Alternative Fuels Infrastructure Regulation) for regulatory reporting. **Null vs empty semantics:** - `null` - Not yet specified by the operator (unknown). Omitted from DATEX II reporting. - `[]` (empty array) - The operator explicitly confirmed that no payment options are available at this location. **Request behavior (POST/PATCH):** - Optional field when creating or updating locations - Send `null` to clear all payment options - Send `[]` to store an empty payment options list - Duplicate values are automatically de-duplicated before storage - Omit the field in PATCH requests to leave the existing value unchanged **Response behavior (GET):** - Field is omitted from the response when no payment options are configured (null in database) - When payment options are configured but the array is empty, returns an empty array `[]` - When present, returns an array of valid enum values listed above" }, "acceptedPaymentBrands": { "type": "array", "items": { "type": "string", "enum": [ "VISA", "MASTERCARD", "MAESTRO", "AMEX", "GIROCARD", "OTHER" ], "description": "Payment card brands accepted at the charging location. Only applicable when payment terminal options (`EMV_CHIP_TERMINAL` or `NFC_CONTACTLESS_TERMINAL`) are present in `paymentOptions`. - `VISA` - Visa - `MASTERCARD` - Mastercard - `MAESTRO` - Maestro - `AMEX` - American Express - `GIROCARD` - Girocard - `OTHER` - Other payment brand" }, "nullable": true, "description": "Payment card brands accepted at the charging location. Only applicable when `paymentOptions` includes a payment terminal option (`EMV_CHIP_TERMINAL` or `NFC_CONTACTLESS_TERMINAL`). If `paymentOptions` does not contain any terminal option, any provided `acceptedPaymentBrands` value is silently ignored and stored as `null`. **Null vs empty semantics:** - `null` - Not yet specified or not applicable (no terminal options in `paymentOptions`). - `[]` (empty array) - The operator explicitly confirmed that no specific payment brands are accepted. **Request behavior (POST/PATCH):** - Optional field when creating or updating locations - Send `null` to clear all accepted payment brands - Send `[]` to store an empty accepted payment brands list - Duplicate values are automatically de-duplicated before storage - Omit the field in PATCH requests to leave the existing value unchanged - If `paymentOptions` does not contain `EMV_CHIP_TERMINAL` or `NFC_CONTACTLESS_TERMINAL`, this field is silently stored as `null` **Response behavior (GET):** - Field is omitted from the response when no accepted payment brands are configured (null in database) - When accepted payment brands are configured but the array is empty, returns an empty array `[]` - When present, returns an array of valid enum values listed above" }, "workingHours": { "type": "object", "properties": { "isAlwaysOpen": { "type": "boolean", "description": "Indicates that the location is always open for charging. If set to false, the `hours` field is required, otherwise it should be ignored." }, "allowChargingOutsideWorkingHours": { "type": "boolean", "description": "When enabled, charging sessions can be started even when the location is outside its working hours. The location will still appear as closed to users. When this is true, stopSessionOutsideWorkingHours is effectively ignored." }, "stopSessionOutsideWorkingHours": { "type": "boolean", "nullable": true, "description": "If a User has initiated a charging session during Working hours but it is already outside of the Working hours, the session will be terminated by the system. This is valid only for Users that are not included in one of the User Groups for which the Location is available 24/7." }, "alwaysOpenForUserGroupIds": { "type": "array", "items": { "type": "number" }, "example": [ 1, 2, 3 ], "nullable": true }, "hours": { "type": "object", "properties": { "monday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "tuesday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "wednesday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "thursday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "friday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "saturday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "sunday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" } }, "nullable": true, "description": "The times should be considered to be in the location/tenant timezone. If a day does not have any working hour intervals, it will be treated as closed for the whole day." } } }, "tags": { "type": "array", "items": { "type": "string" } }, "externalAppData": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Used to hold any external application data related to the Location." } }, "required": [ "name", "geoposition", "address", "country" ] } } } }, "responses": { "201": { "description": "Location created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0/{location}", "method": "GET", "operationId": "locationRead", "summary": "Location / Read", "description": "Get a location", "tags": [ "resource / locations" ], "responses": { "200": { "description": "Location returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0/{location}", "method": "DELETE", "operationId": "locationDelete", "summary": "Location / Delete", "description": "Delete a location", "tags": [ "resource / locations" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0/{location}", "method": "PATCH", "operationId": "locationUpdate", "summary": "Location / Update", "description": "Update a location", "tags": [ "resource / locations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "externalId": { "type": "string", "nullable": true }, "name": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Deprecated." }, "description": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "shortDescription": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "additionalDescription": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "geoposition": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ] }, "address": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "The full address of the location" }, "streetAddress": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "The street address of the location" }, "city": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true, "description": "When country is not in US, AU, CA, UM or RO, you can provide the region" }, "state": { "anyOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "When the country is US." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "When the country is AU." }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" ], "description": "When the country is CA." }, { "type": "string", "enum": [ "81", "84", "85", "67", "89", "71", "76", "95", "79" ], "description": "When the country is UM." }, { "type": "string", "enum": [ "AB", "AR", "AG", "BC", "BH", "BN", "BT", "BV", "BR", "B", "BZ", "CL", "CS", "CT", "CV", "DB", "DJ", "GL", "GR", "GJ", "HR", "HD", "IL", "IS", "IF", "MM", "MH", "MS", "NT", "OT", "PH", "SM", "SJ", "SB", "SV", "TR", "TM", "TL", "VS", "VL", "VN" ], "description": "When the country is RO." } ], "description": "When the selected country is one of US, AU, CA, UM or RO" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "postCode": { "type": "string", "nullable": true, "description": "Postal code of the location. Required for most countries — omitting it for those will result in a validation error." }, "timezone": { "type": "string", "nullable": true, "description": "A valid timezone in the form of Area/Location, required when `Allow Multiple Time Zones` option is turned on in the Timezone Setting." }, "parkingType": { "type": "string", "enum": [ "ALONG_MOTORWAY", "PARKING_GARAGE", "PARKING_LOT", "ON_DRIVEWAY", "ON_STREET", "UNDERGROUND_GARAGE", "IS_TENT", "SECURE" ], "nullable": true, "description": "Indicates the type of parking available at the charging location. This field helps EV drivers understand the physical parking environment before arrival. **Valid values:** - `ALONG_MOTORWAY` - Located along a motorway/highway, typically at rest areas or service stations - `PARKING_GARAGE` - Multi-level parking garage structure, either above-ground or mixed-use - `PARKING_LOT` - Surface parking lot, open-air parking area - `ON_DRIVEWAY` - Located on a private driveway, typically residential or small business - `ON_STREET` - Street-side parking, curbside charging locations - `UNDERGROUND_GARAGE` - Underground parking structure, subterranean parking facility - `IS_TENT` - Site located on the Trans-European Transport Network (Lithuania NAP / Via Lietuva extension; may not be interpreted by all roaming partners) - `SECURE` - Restricted-access parking such as gated lots, key-card access, or staffed parking (Lithuania NAP / Via Lietuva extension; may not be interpreted by all roaming partners) **Request behavior (POST/PATCH):** - Optional field when creating or updating locations - Send `null` to clear the parking type - Omit the field in PATCH requests to leave the existing value unchanged **Response behavior (GET):** - Field is omitted from the response when no parking type is configured (null in database) - When present, returns one of the valid enum values listed above" }, "accessibilityType": { "type": "string", "enum": [ "free_publicly_accessible", "restricted_access", "paid_publicly_accessible" ], "description": "Determines how the accessibility of the location is reported to OICP (Hubject) roaming partners. - `free_publicly_accessible` - The charge point is reachable without a fee - `restricted_access` - Permission is required to reach the charge point (e.g. company or building complex) - `paid_publicly_accessible` - A fee is required to reach the charge point (e.g. a paid parking garage)" }, "accessMethods": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "TOKEN", "LICENSE_PLATE", "ACCESS_CODE", "INTERCOM", "PARKING_TICKET" ] }, "example": [ "OPEN", "TOKEN" ], "nullable": true, "description": "Physical access methods available at this location. Multiple methods can be selected if the site supports different access types. **Request behavior (POST/PATCH):** - Optional field when creating or updating locations - Send `null` to clear all access methods - Send `[]` to store an empty access methods list - Duplicate values are automatically de-duplicated before storage - Omit the field in PATCH requests to leave the existing value unchanged **Response behavior (GET):** - Field is omitted from the response when no access methods are configured (null in database) - When access methods are configured but the array is empty, returns an empty array `[]` - When present, returns an array of valid enum values listed above **Available methods:** - `OPEN` - Publicly accessible without restrictions - `TOKEN` - Access via RFID token or card - `LICENSE_PLATE` - Access via license plate recognition - `ACCESS_CODE` - Access via PIN/access code entry - `INTERCOM` - Access via intercom system - `PARKING_TICKET` - Access via parking ticket validation" }, "facilities": { "type": "array", "items": { "type": "string", "enum": [ "AIRPORT", "BATHROOM", "BIKE_SHARING", "BUS_STOP", "CAFE", "CARPOOL_PARKING", "FUEL_STATION", "HOTEL", "MALL", "METRO_STATION", "MUSEUM", "NATURE", "PARKING_LOT", "RECREATION_AREA", "RESTAURANT", "SPORT", "STAFFED", "SUPERMARKET", "TAXI_STAND", "TRAIN_STATION", "TRAM_STOP", "WIFI" ] }, "nullable": true, "description": "Describes amenities and facilities available at or near the charging location. Most values are self-explanatory. Special categories include: - `RECREATION_AREA` - Parks, playgrounds, or leisure facilities - `CARPOOL_PARKING` - Dedicated parking for carpooling/ridesharing - `NATURE` - Natural attractions or green spaces - `STAFFED` - Location has staff present - `BATHROOM` - Bathroom facilities available **Request behavior (POST/PATCH):** - Optional field when creating or updating locations - Send `null` to clear all facilities - Send `[]` to store an empty facilities list - Duplicate values are automatically de-duplicated before storage - Omit the field in PATCH requests to leave the existing value unchanged **Response behavior (GET):** - Field is omitted from the response when no facilities are configured (null in database) - When facilities are configured but the array is empty, returns an empty array `[]` - When present, returns an array of valid enum values listed above" }, "workingHours": { "type": "object", "properties": { "isAlwaysOpen": { "type": "boolean", "description": "Indicates that the location is always open for charging. If set to false, the `hours` field is required, otherwise it should be ignored." }, "allowChargingOutsideWorkingHours": { "type": "boolean", "description": "When enabled, charging sessions can be started even when the location is outside its working hours. The location will still appear as closed to users. When this is true, stopSessionOutsideWorkingHours is effectively ignored." }, "stopSessionOutsideWorkingHours": { "type": "boolean", "nullable": true, "description": "If a User has initiated a charging session during Working hours but it is already outside of the Working hours, the session will be terminated by the system. This is valid only for Users that are not included in one of the User Groups for which the Location is available 24/7." }, "alwaysOpenForUserGroupIds": { "type": "array", "items": { "type": "number" }, "example": [ 1, 2, 3 ], "nullable": true }, "hours": { "type": "object", "properties": { "monday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "tuesday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "wednesday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "thursday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "friday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "saturday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" }, "sunday": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "time", "example": "01:00" }, "end": { "type": "string", "format": "time", "example": "09:00" } }, "required": [ "start", "end" ] }, "description": "Working hours interval for single day" } }, "nullable": true, "description": "The times should be considered to be in the location/tenant timezone. If a day does not have any working hour intervals, it will be treated as closed for the whole day." } } }, "tags": { "type": "array", "items": { "type": "string" } }, "externalAppData": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Used to hold any external application data related to the Location." } } } } } }, "responses": { "200": { "description": "Location updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0/{location}/charging-zones", "method": "GET", "operationId": "locationChargingZonesListing", "summary": "Location / Charging Zones / Listing", "description": "Get all Charging Zones", "tags": [ "resource / locations" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/locations/v2.0/{location}/charging-zones", "method": "POST", "operationId": "locationChargingZoneCreate", "summary": "Location / Charging Zone / Create", "description": "Create a new Charging Zone", "tags": [ "resource / locations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "description": "Internal name of the Charging Zone. This isn't visible to end-users in the app." }, "floorLevel": { "type": "string", "maxLength": 4, "description": "Floor level where charging zone is located (e.g., '2', 'B1', 'G'). Optional, max 4 characters." }, "locationId": { "type": "integer", "description": "The ID of the Location, which the Charging Zone belongs to." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "additionalInfo": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "title": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "description": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } } }, "description": "Additional information for the charging zone that is shown in the mobile app when the Location is viewed." } }, "required": [ "name", "status" ] } } } }, "responses": { "201": { "description": "Charging Zone is created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0/{location}/charging-zones/{chargingZone}", "method": "GET", "operationId": "locationChargingZoneRead", "summary": "Location / Charging Zone / Read", "description": "Get a Charging Zone", "tags": [ "resource / locations" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0/{location}/charging-zones/{chargingZone}", "method": "DELETE", "operationId": "locationChargingZoneDelete", "summary": "Location / Charging Zone / Delete", "tags": [ "resource / locations" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0/{location}/charging-zones/{chargingZone}", "method": "PATCH", "operationId": "locationChargingZoneUpdate", "summary": "Location / Charging Zones / Update", "description": "Update a existing Charging Zone", "tags": [ "resource / locations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "description": "Internal name of the Charging Zone. This isn't visible to end-users in the app." }, "floorLevel": { "type": "string", "maxLength": 4, "nullable": true, "description": "Floor level where charging zone is located (e.g., '2', 'B1', 'G'). Optional, max 4 characters." }, "locationId": { "type": "integer", "description": "The ID of the Location, which the Charging Zone belongs to." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "additionalInfo": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "title": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "description": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } } }, "description": "Additional information for the charging zone that is shown in the mobile app when the Location is viewed." } } } } } }, "responses": { "200": { "description": "Charging Zone is updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0/{location}/notes", "method": "GET", "operationId": "locationNotesListing", "summary": "Location / Notes / Listing", "description": "List all notes for a specific location. Notes are returned with pinned notes first, then ordered by creation date descending. **Required permission:** `Notes.view`", "tags": [ "resource / locations" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "pinned": { "type": "boolean", "example": true, "description": "Filter by pinned status" }, "createdAfter": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z", "description": "Filter notes created on or after this ISO-8601 datetime" }, "createdBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes created on or before this ISO-8601 datetime" }, "updatedAfter": { "type": "string", "format": "date-time", "example": "2025-12-01T00:00:00Z", "description": "Filter notes updated on or after this ISO-8601 datetime (useful for delta sync)" }, "updatedBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes updated on or before this ISO-8601 datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0/{location}/notes", "method": "POST", "operationId": "locationNoteCreate", "summary": "Location / Note / Create", "description": "Create a new note for a specific location. **Required permission:** `Notes.create`", "tags": [ "resource / locations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Important maintenance note", "description": "Short summary or title of the note (required)" }, "details": { "type": "string", "maxLength": 2000, "example": "This charge point requires monthly inspection due to high usage.", "description": "Detailed content of the note (optional)" }, "pinned": { "type": "boolean", "default": false, "example": false, "description": "Whether the note should be pinned (optional, defaults to false)" } }, "required": [ "summary" ] } } } }, "responses": { "201": { "description": "Note created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0/{location}/notes/{note}", "method": "GET", "operationId": "locationNoteShow", "summary": "Location / Note / Read", "description": "Get a specific note for a location. **Required permission:** `Notes.view`", "tags": [ "resource / locations" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0/{location}/notes/{note}", "method": "DELETE", "operationId": "locationNoteDelete", "summary": "Location / Note / Delete", "description": "Delete a specific note from a location. Notes are permanently deleted (hard delete). **Required permission:** `Notes.delete`", "tags": [ "resource / locations" ], "responses": { "204": { "description": "Note deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/locations/v2.0/{location}/notes/{note}", "method": "PATCH", "operationId": "locationNoteUpdate", "summary": "Location / Note / Update", "description": "Update a specific note for a location. **Required permissions:** - `Notes.update` for updating summary and details - `Notes.pin` for updating the pinned field (in addition to Notes.update if other fields are included)", "tags": [ "resource / locations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Updated maintenance note", "description": "Short summary or title of the note" }, "details": { "type": "string", "maxLength": 2000, "example": "Updated inspection schedule.", "nullable": true, "description": "Detailed content of the note. Send null to clear." }, "pinned": { "type": "boolean", "example": true, "description": "Whether the note should be pinned. Requires Notes.pin permission." } } } } } }, "responses": { "200": { "description": "Note updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/operators/v1.0", "method": "GET", "operationId": "operatorsListing", "summary": "Operators / Listing", "description": "Get all operators the authenticated user has access to", "tags": [ "resource / operators" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/operators/v1.0/{operator}", "method": "GET", "operationId": "operatorRead", "summary": "Operator / Read", "description": "Get a single operator by ID", "tags": [ "resource / operators" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/parking-spaces/v1.0", "method": "GET", "operationId": "listParkingSpace", "summary": "Parking Space / Listing", "description": "Get all Parking spaces", "tags": [ "resource / parking spaces" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "externalId": { "type": "string" }, "evseId": { "type": "string", "format": "integer", "description": "Only list Parking spaces on a certain EVSE" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the parking spaces that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the parking spaces that were last updated on and before this datetime" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the parking space records that were created on and after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the parking space records that were created on and before this datetime" }, "parkingDirection": { "type": "string", "enum": [ "parallel", "perpendicular", "angle" ], "description": "Parking space orientation relative to the street or access lane: - **parallel**: Vehicle parked parallel to the street or access lane - **perpendicular**: Vehicle parked perpendicular (90 degrees) to the street or access lane - **angle**: Vehicle parked at an angle to the street or access lane (typically 45-60 degrees)" }, "roofed": { "type": "boolean", "description": "Filter by whether the parking space has overhead coverage/roof protection" }, "lighting": { "type": "boolean", "description": "Filter by whether the parking space has lighting installed" }, "dangerousGoodsAllowed": { "type": "boolean", "description": "Filter by whether vehicles carrying dangerous goods are permitted" }, "reservationRequired": { "type": "boolean", "description": "Filter by whether prior reservation is required to use this parking space" } } } }, "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "evses", "accessibleEvses" ] } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/parking-spaces/v1.0", "method": "POST", "operationId": "createParkingSpace", "summary": "Parking Space / Create", "description": "Create new Parking Space", "tags": [ "resource / parking spaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the parking space." }, "locationId": { "type": "integer", "description": "The ID of the location this parking space belongs to." }, "label": { "type": "string", "description": "Display label for the parking space (max 255 characters)." }, "externalId": { "type": "string", "description": "External system identifier for integration purposes. Unique per operator." }, "latitude": { "type": "number", "format": "float", "minimum": -90, "maximum": 90, "nullable": true, "description": "GPS latitude coordinate (7 decimal places precision)." }, "longitude": { "type": "number", "format": "float", "minimum": -180, "maximum": 180, "nullable": true, "description": "GPS longitude coordinate (7 decimal places precision)." }, "directions": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Textual navigation instructions to find the parking space." }, "properties": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0, "maximum": 500, "nullable": true, "description": "Width of the parking space in centimeters." }, "length": { "type": "integer", "minimum": 0, "maximum": 2000, "nullable": true, "description": "Length of the parking space in centimeters." }, "driveThrough": { "type": "boolean", "default": false, "description": "Indicates if the parking space supports drive-through access." }, "refrigerationOutlet": { "type": "boolean", "default": false, "description": "Indicates if the parking space has a refrigeration outlet for auxiliary power." }, "parkingDirection": { "type": "string", "enum": [ "parallel", "perpendicular", "angle" ], "description": "Parking space orientation relative to the street or access lane: - **parallel**: Vehicle parked parallel to the street or access lane - **perpendicular**: Vehicle parked perpendicular (90 degrees) to the street or access lane - **angle**: Vehicle parked at an angle to the street or access lane (typically 45-60 degrees)" }, "roofed": { "type": "boolean", "default": false, "description": "Indicates whether the parking space has overhead coverage/roof protection." }, "lighting": { "type": "boolean", "default": false, "description": "Indicates whether the parking space has lighting installed." } }, "description": "Physical characteristics and special features of the parking space." }, "accessibility": { "type": "object", "properties": { "disabilitiesAccessible": { "type": "boolean", "default": false, "description": "Indicates if the parking space is suitable but not necessarily designated or restricted only for use by people with disabilities." }, "kerbHeightCm": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0, "description": "Height of the kerb in centimeters." }, "hearingLoop": { "type": "boolean", "default": false, "description": "Indicates if a hearing loop system is available." }, "tactilePaving": { "type": "boolean", "default": false, "description": "Indicates if tactile paving is present for visually impaired users." }, "brailleSignage": { "type": "boolean", "default": false, "description": "Indicates if braille signage is available." }, "visualSignage": { "type": "boolean", "default": false, "description": "Indicates if clear visual signage is present." }, "audioAnnouncements": { "type": "boolean", "default": false, "description": "Indicates if audio announcements are available." }, "accessiblePaymentTerminal": { "type": "boolean", "default": false, "description": "Indicates if an accessible payment terminal is available." } }, "description": "Accessibility features for disabled users." }, "vehicleRestrictions": { "type": "object", "properties": { "maxWidth": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum vehicle width in centimeters." }, "maxLength": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum vehicle length in centimeters." }, "maxHeight": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum vehicle height in centimeters." }, "maxWeight": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum vehicle weight in kilograms." }, "supportedVehicleTypes": { "type": "array", "items": { "type": "string", "enum": [ "twoAndThreeWheelVehiclesAndQuadricycles", "passengerVehicles", "passengerVehiclesWithTrailer", "lightDutyVans", "heavyDutyTractorUnitsWithoutTrailer", "heavyDutyTrucksWithoutArticulationPoint", "heavyDutyTrucksWithTrailerAttached", "busesOrMotorCoaches" ], "description": "Supported vehicle types compliant with OCPI 2.3 standard: - **twoAndThreeWheelVehiclesAndQuadricycles**: Motorcycles, scooters, quadricycles - **passengerVehicles**: Standard passenger cars - **passengerVehiclesWithTrailer**: Cars towing trailers - **lightDutyVans**: Light commercial vans - **heavyDutyTractorUnitsWithoutTrailer**: Tractor units (no trailer attached) - **heavyDutyTrucksWithoutArticulationPoint**: Rigid trucks - **heavyDutyTrucksWithTrailerAttached**: Articulated lorries - **busesOrMotorCoaches**: Buses and coaches" }, "nullable": true, "description": "Array of OCPI 2.3 compliant vehicle types allowed at this parking space. Send null or empty array to clear." }, "restrictedToSpecificVehicleTypes": { "type": "boolean", "default": false, "description": "Indicates that the parking space is only allowed for the specific vehicle types." }, "evOnly": { "type": "boolean", "default": false, "description": "Parking space is restricted to electric vehicles only." }, "whileChargingOnly": { "type": "boolean", "default": false, "description": "Parking allowed only while actively charging." }, "disabledPermitOnly": { "type": "boolean", "default": false, "description": "Disabled parking permit required." }, "customersOnly": { "type": "boolean", "default": false, "description": "Restricted to customers of the operator." }, "staffOnly": { "type": "boolean", "default": false, "description": "Restricted to staff/employees only." }, "deliveriesOnly": { "type": "boolean", "default": false, "description": "Restricted to delivery vehicles only." }, "permitRequired": { "type": "boolean", "default": false, "description": "General parking permit required." }, "taxisOnly": { "type": "boolean", "default": false, "description": "Restricted to licensed taxis only." }, "parkAndRide": { "type": "boolean", "default": false, "description": "Designated as a park and ride facility." }, "dangerousGoodsAllowed": { "type": "boolean", "default": false, "description": "Indicates whether vehicles carrying dangerous goods are permitted to use this parking space." }, "reservationRequired": { "type": "boolean", "default": false, "description": "Indicates whether prior reservation is required to use this parking space." }, "timeLimit": { "type": "integer", "minimum": 0, "description": "Maximum allowed parking duration in minutes. Value of 0 indicates no time limit." } }, "description": "Vehicle size restrictions and access rules." }, "compliance": { "type": "object", "properties": { "standards": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "description": "List of compliance standards applicable to this parking space (e.g., \"PAS 1899\", \"ISO 17438\", \"3-101/D1-26\"). Each standard identifier limited to 100 characters. Known compliance standards: * `3-101/D1-26` — Lithuanian national standard for disabled-access parking, required by the Via Lietuva NAP for wheelchair-accessible parking spaces. * `PAS 1899` — BSI/Motability publicly available specification for accessible electric vehicle charging. * `ISO 17438` — ITS standard family for electronic information exchange about parking facilities." }, "apdsReference": { "type": "string", "maxLength": 255, "description": "Reference identifier for the Accessible Parking Data Standard (APDS) specification." } }, "description": "Compliance standards and certifications applicable to this parking space." }, "disabilitiesAccessible": { "type": "boolean" }, "evses": { "type": "array", "items": { "type": "integer" }, "description": "The list of EVSE IDs at the same Parking Space. EVSEs must belong to the same charging zone. Each EVSE will be auto-assigned with position \"front\" and marked as not primary." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "enabled", "description": "Current operational status of the parking space: - **enabled**: Parking space is active and can be used (default) - **disabled**: Parking space is inactive and cannot be used" }, "occupancyStatus": { "type": "string", "enum": [ "unknown", "available", "occupied", "blocked" ], "default": "unknown", "description": "Current occupancy status of the parking space: - **unknown**: Occupancy status cannot be determined (default) - **available**: Parking space is free and ready for use - **occupied**: Parking space is currently in use - **blocked**: Parking space is physically blocked (roadworks, barriers, planned maintenance)" } }, "required": [ "locationId", "label" ] } } } }, "responses": { "201": { "description": "Parking Space created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/parking-spaces/v1.0/{parkingSpace}", "method": "GET", "operationId": "getParkingSpace", "summary": "Parking Space / Read", "description": "Get Parking Space", "tags": [ "resource / parking spaces" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "evses", "accessibleEvses" ] } } } } }, "responses": { "200": { "description": "Parking Space returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/parking-spaces/v1.0/{parkingSpace}", "method": "PUT", "operationId": "updateParkingSpace", "summary": "Parking Space / Update", "description": "Update Parking Space", "deprecated": true, "tags": [ "resource / parking spaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the parking space." }, "locationId": { "type": "integer", "description": "The ID of the location this parking space belongs to." }, "label": { "type": "string", "description": "Display label for the parking space (max 255 characters)." }, "externalId": { "type": "string", "description": "External system identifier for integration purposes. Unique per operator." }, "latitude": { "type": "number", "format": "float", "minimum": -90, "maximum": 90, "nullable": true, "description": "GPS latitude coordinate (7 decimal places precision)." }, "longitude": { "type": "number", "format": "float", "minimum": -180, "maximum": 180, "nullable": true, "description": "GPS longitude coordinate (7 decimal places precision)." }, "directions": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Textual navigation instructions to find the parking space." }, "properties": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0, "maximum": 500, "nullable": true, "description": "Width of the parking space in centimeters." }, "length": { "type": "integer", "minimum": 0, "maximum": 2000, "nullable": true, "description": "Length of the parking space in centimeters." }, "driveThrough": { "type": "boolean", "default": false, "description": "Indicates if the parking space supports drive-through access." }, "refrigerationOutlet": { "type": "boolean", "default": false, "description": "Indicates if the parking space has a refrigeration outlet for auxiliary power." }, "parkingDirection": { "type": "string", "enum": [ "parallel", "perpendicular", "angle" ], "description": "Parking space orientation relative to the street or access lane: - **parallel**: Vehicle parked parallel to the street or access lane - **perpendicular**: Vehicle parked perpendicular (90 degrees) to the street or access lane - **angle**: Vehicle parked at an angle to the street or access lane (typically 45-60 degrees)" }, "roofed": { "type": "boolean", "default": false, "description": "Indicates whether the parking space has overhead coverage/roof protection." }, "lighting": { "type": "boolean", "default": false, "description": "Indicates whether the parking space has lighting installed." } }, "description": "Physical characteristics and special features of the parking space." }, "accessibility": { "type": "object", "properties": { "disabilitiesAccessible": { "type": "boolean", "default": false, "description": "Indicates if the parking space is suitable but not necessarily designated or restricted only for use by people with disabilities." }, "kerbHeightCm": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0, "description": "Height of the kerb in centimeters." }, "hearingLoop": { "type": "boolean", "default": false, "description": "Indicates if a hearing loop system is available." }, "tactilePaving": { "type": "boolean", "default": false, "description": "Indicates if tactile paving is present for visually impaired users." }, "brailleSignage": { "type": "boolean", "default": false, "description": "Indicates if braille signage is available." }, "visualSignage": { "type": "boolean", "default": false, "description": "Indicates if clear visual signage is present." }, "audioAnnouncements": { "type": "boolean", "default": false, "description": "Indicates if audio announcements are available." }, "accessiblePaymentTerminal": { "type": "boolean", "default": false, "description": "Indicates if an accessible payment terminal is available." } }, "description": "Accessibility features for disabled users." }, "vehicleRestrictions": { "type": "object", "properties": { "maxWidth": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum vehicle width in centimeters." }, "maxLength": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum vehicle length in centimeters." }, "maxHeight": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum vehicle height in centimeters." }, "maxWeight": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum vehicle weight in kilograms." }, "supportedVehicleTypes": { "type": "array", "items": { "type": "string", "enum": [ "twoAndThreeWheelVehiclesAndQuadricycles", "passengerVehicles", "passengerVehiclesWithTrailer", "lightDutyVans", "heavyDutyTractorUnitsWithoutTrailer", "heavyDutyTrucksWithoutArticulationPoint", "heavyDutyTrucksWithTrailerAttached", "busesOrMotorCoaches" ], "description": "Supported vehicle types compliant with OCPI 2.3 standard: - **twoAndThreeWheelVehiclesAndQuadricycles**: Motorcycles, scooters, quadricycles - **passengerVehicles**: Standard passenger cars - **passengerVehiclesWithTrailer**: Cars towing trailers - **lightDutyVans**: Light commercial vans - **heavyDutyTractorUnitsWithoutTrailer**: Tractor units (no trailer attached) - **heavyDutyTrucksWithoutArticulationPoint**: Rigid trucks - **heavyDutyTrucksWithTrailerAttached**: Articulated lorries - **busesOrMotorCoaches**: Buses and coaches" }, "nullable": true, "description": "Array of OCPI 2.3 compliant vehicle types allowed at this parking space. Send null or empty array to clear." }, "restrictedToSpecificVehicleTypes": { "type": "boolean", "default": false, "description": "Indicates that the parking space is only allowed for the specific vehicle types." }, "evOnly": { "type": "boolean", "default": false, "description": "Parking space is restricted to electric vehicles only." }, "whileChargingOnly": { "type": "boolean", "default": false, "description": "Parking allowed only while actively charging." }, "disabledPermitOnly": { "type": "boolean", "default": false, "description": "Disabled parking permit required." }, "customersOnly": { "type": "boolean", "default": false, "description": "Restricted to customers of the operator." }, "staffOnly": { "type": "boolean", "default": false, "description": "Restricted to staff/employees only." }, "deliveriesOnly": { "type": "boolean", "default": false, "description": "Restricted to delivery vehicles only." }, "permitRequired": { "type": "boolean", "default": false, "description": "General parking permit required." }, "taxisOnly": { "type": "boolean", "default": false, "description": "Restricted to licensed taxis only." }, "parkAndRide": { "type": "boolean", "default": false, "description": "Designated as a park and ride facility." }, "dangerousGoodsAllowed": { "type": "boolean", "default": false, "description": "Indicates whether vehicles carrying dangerous goods are permitted to use this parking space." }, "reservationRequired": { "type": "boolean", "default": false, "description": "Indicates whether prior reservation is required to use this parking space." }, "timeLimit": { "type": "integer", "minimum": 0, "description": "Maximum allowed parking duration in minutes. Value of 0 indicates no time limit." } }, "description": "Vehicle size restrictions and access rules." }, "compliance": { "type": "object", "properties": { "standards": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "description": "List of compliance standards applicable to this parking space (e.g., \"PAS 1899\", \"ISO 17438\", \"3-101/D1-26\"). Each standard identifier limited to 100 characters. Known compliance standards: * `3-101/D1-26` — Lithuanian national standard for disabled-access parking, required by the Via Lietuva NAP for wheelchair-accessible parking spaces. * `PAS 1899` — BSI/Motability publicly available specification for accessible electric vehicle charging. * `ISO 17438` — ITS standard family for electronic information exchange about parking facilities." }, "apdsReference": { "type": "string", "maxLength": 255, "description": "Reference identifier for the Accessible Parking Data Standard (APDS) specification." } }, "description": "Compliance standards and certifications applicable to this parking space." }, "disabilitiesAccessible": { "type": "boolean" }, "evses": { "type": "array", "items": { "type": "integer" }, "description": "The list of EVSE IDs at the same Parking Space. EVSEs must belong to the same charging zone. Each EVSE will be auto-assigned with position \"front\" and marked as not primary." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "enabled", "description": "Current operational status of the parking space: - **enabled**: Parking space is active and can be used (default) - **disabled**: Parking space is inactive and cannot be used" }, "occupancyStatus": { "type": "string", "enum": [ "unknown", "available", "occupied", "blocked" ], "default": "unknown", "description": "Current occupancy status of the parking space: - **unknown**: Occupancy status cannot be determined (default) - **available**: Parking space is free and ready for use - **occupied**: Parking space is currently in use - **blocked**: Parking space is physically blocked (roadworks, barriers, planned maintenance)" } }, "required": [ "locationId", "label" ] } } } }, "responses": { "200": { "description": "Parking Space updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/parking-spaces/v1.0/{parkingSpace}", "method": "DELETE", "operationId": "deleteParkingSpace", "summary": "Parking Space / Delete", "description": "Delete Parking Space", "tags": [ "resource / parking spaces" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/parking-spaces/v1.0/{parkingSpace}", "method": "PATCH", "operationId": "parkingSpaceUpdate", "summary": "Parking Space / Update", "description": "Update a Parking Space", "tags": [ "resource / parking spaces" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the parking space." }, "locationId": { "type": "integer", "description": "The ID of the location this parking space belongs to." }, "label": { "type": "string", "description": "Display label for the parking space (max 255 characters)." }, "externalId": { "type": "string", "description": "External system identifier for integration purposes. Unique per operator." }, "latitude": { "type": "number", "format": "float", "minimum": -90, "maximum": 90, "nullable": true, "description": "GPS latitude coordinate (7 decimal places precision)." }, "longitude": { "type": "number", "format": "float", "minimum": -180, "maximum": 180, "nullable": true, "description": "GPS longitude coordinate (7 decimal places precision)." }, "directions": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Textual navigation instructions to find the parking space." }, "properties": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0, "maximum": 500, "nullable": true, "description": "Width of the parking space in centimeters." }, "length": { "type": "integer", "minimum": 0, "maximum": 2000, "nullable": true, "description": "Length of the parking space in centimeters." }, "driveThrough": { "type": "boolean", "default": false, "description": "Indicates if the parking space supports drive-through access." }, "refrigerationOutlet": { "type": "boolean", "default": false, "description": "Indicates if the parking space has a refrigeration outlet for auxiliary power." }, "parkingDirection": { "type": "string", "enum": [ "parallel", "perpendicular", "angle" ], "description": "Parking space orientation relative to the street or access lane: - **parallel**: Vehicle parked parallel to the street or access lane - **perpendicular**: Vehicle parked perpendicular (90 degrees) to the street or access lane - **angle**: Vehicle parked at an angle to the street or access lane (typically 45-60 degrees)" }, "roofed": { "type": "boolean", "default": false, "description": "Indicates whether the parking space has overhead coverage/roof protection." }, "lighting": { "type": "boolean", "default": false, "description": "Indicates whether the parking space has lighting installed." } }, "description": "Physical characteristics and special features of the parking space." }, "accessibility": { "type": "object", "properties": { "disabilitiesAccessible": { "type": "boolean", "default": false, "description": "Indicates if the parking space is suitable but not necessarily designated or restricted only for use by people with disabilities." }, "kerbHeightCm": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0, "description": "Height of the kerb in centimeters." }, "hearingLoop": { "type": "boolean", "default": false, "description": "Indicates if a hearing loop system is available." }, "tactilePaving": { "type": "boolean", "default": false, "description": "Indicates if tactile paving is present for visually impaired users." }, "brailleSignage": { "type": "boolean", "default": false, "description": "Indicates if braille signage is available." }, "visualSignage": { "type": "boolean", "default": false, "description": "Indicates if clear visual signage is present." }, "audioAnnouncements": { "type": "boolean", "default": false, "description": "Indicates if audio announcements are available." }, "accessiblePaymentTerminal": { "type": "boolean", "default": false, "description": "Indicates if an accessible payment terminal is available." } }, "description": "Accessibility features for disabled users." }, "vehicleRestrictions": { "type": "object", "properties": { "maxWidth": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum vehicle width in centimeters." }, "maxLength": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum vehicle length in centimeters." }, "maxHeight": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum vehicle height in centimeters." }, "maxWeight": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum vehicle weight in kilograms." }, "supportedVehicleTypes": { "type": "array", "items": { "type": "string", "enum": [ "twoAndThreeWheelVehiclesAndQuadricycles", "passengerVehicles", "passengerVehiclesWithTrailer", "lightDutyVans", "heavyDutyTractorUnitsWithoutTrailer", "heavyDutyTrucksWithoutArticulationPoint", "heavyDutyTrucksWithTrailerAttached", "busesOrMotorCoaches" ], "description": "Supported vehicle types compliant with OCPI 2.3 standard: - **twoAndThreeWheelVehiclesAndQuadricycles**: Motorcycles, scooters, quadricycles - **passengerVehicles**: Standard passenger cars - **passengerVehiclesWithTrailer**: Cars towing trailers - **lightDutyVans**: Light commercial vans - **heavyDutyTractorUnitsWithoutTrailer**: Tractor units (no trailer attached) - **heavyDutyTrucksWithoutArticulationPoint**: Rigid trucks - **heavyDutyTrucksWithTrailerAttached**: Articulated lorries - **busesOrMotorCoaches**: Buses and coaches" }, "nullable": true, "description": "Array of OCPI 2.3 compliant vehicle types allowed at this parking space. Send null or empty array to clear." }, "restrictedToSpecificVehicleTypes": { "type": "boolean", "default": false, "description": "Indicates that the parking space is only allowed for the specific vehicle types." }, "evOnly": { "type": "boolean", "default": false, "description": "Parking space is restricted to electric vehicles only." }, "whileChargingOnly": { "type": "boolean", "default": false, "description": "Parking allowed only while actively charging." }, "disabledPermitOnly": { "type": "boolean", "default": false, "description": "Disabled parking permit required." }, "customersOnly": { "type": "boolean", "default": false, "description": "Restricted to customers of the operator." }, "staffOnly": { "type": "boolean", "default": false, "description": "Restricted to staff/employees only." }, "deliveriesOnly": { "type": "boolean", "default": false, "description": "Restricted to delivery vehicles only." }, "permitRequired": { "type": "boolean", "default": false, "description": "General parking permit required." }, "taxisOnly": { "type": "boolean", "default": false, "description": "Restricted to licensed taxis only." }, "parkAndRide": { "type": "boolean", "default": false, "description": "Designated as a park and ride facility." }, "dangerousGoodsAllowed": { "type": "boolean", "default": false, "description": "Indicates whether vehicles carrying dangerous goods are permitted to use this parking space." }, "reservationRequired": { "type": "boolean", "default": false, "description": "Indicates whether prior reservation is required to use this parking space." }, "timeLimit": { "type": "integer", "minimum": 0, "description": "Maximum allowed parking duration in minutes. Value of 0 indicates no time limit." } }, "description": "Vehicle size restrictions and access rules." }, "compliance": { "type": "object", "properties": { "standards": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "description": "List of compliance standards applicable to this parking space (e.g., \"PAS 1899\", \"ISO 17438\", \"3-101/D1-26\"). Each standard identifier limited to 100 characters. Known compliance standards: * `3-101/D1-26` — Lithuanian national standard for disabled-access parking, required by the Via Lietuva NAP for wheelchair-accessible parking spaces. * `PAS 1899` — BSI/Motability publicly available specification for accessible electric vehicle charging. * `ISO 17438` — ITS standard family for electronic information exchange about parking facilities." }, "apdsReference": { "type": "string", "maxLength": 255, "description": "Reference identifier for the Accessible Parking Data Standard (APDS) specification." } }, "description": "Compliance standards and certifications applicable to this parking space." }, "disabilitiesAccessible": { "type": "boolean" }, "evses": { "type": "array", "items": { "type": "integer" }, "description": "The list of EVSE IDs at the same Parking Space. EVSEs must belong to the same charging zone. Each EVSE will be auto-assigned with position \"front\" and marked as not primary." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "enabled", "description": "Current operational status of the parking space: - **enabled**: Parking space is active and can be used (default) - **disabled**: Parking space is inactive and cannot be used" }, "occupancyStatus": { "type": "string", "enum": [ "unknown", "available", "occupied", "blocked" ], "default": "unknown", "description": "Current occupancy status of the parking space: - **unknown**: Occupancy status cannot be determined (default) - **available**: Parking space is free and ready for use - **occupied**: Parking space is currently in use - **blocked**: Parking space is physically blocked (roadworks, barriers, planned maintenance)" } } } } } }, "responses": { "200": { "description": "Parking Space updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/parking-spaces/v1.0/{parkingSpace}/evses", "method": "GET", "operationId": "parkingSpacesEvsesListing", "summary": "Parking Space / EVSEs / Listing", "description": "Get all EVSEs associated with this parking space.", "tags": [ "resource / parking spaces" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/parking-spaces/v1.0/{parkingSpace}/evses", "method": "PUT", "operationId": "parkingSpacesEvsesSync", "summary": "Parking Space / EVSEs / Update", "description": "Sync multiple EVSEs to the Parking Space at once, setting their position and primary status.", "tags": [ "resource / parking spaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "parkingSpaceId": { "type": "integer", "description": "The ID of the associated parking space." }, "evseId": { "type": "integer", "description": "The ID of the associated EVSE." }, "position": { "type": "string", "enum": [ "front", "rear", "left", "right", "frontLeft", "frontRight", "rearLeft", "rearRight" ], "description": "Physical position of the EVSE relative to the parking space: - **front**: EVSE at front of parking space - **rear**: EVSE at rear of parking space - **left**: EVSE on left side of parking space - **right**: EVSE on right side of parking space - **frontLeft**: EVSE at front-left corner - **frontRight**: EVSE at front-right corner - **rearLeft**: EVSE at rear-left corner - **rearRight**: EVSE at rear-right corner" }, "isPrimary": { "type": "boolean", "description": "Indicates if this is the primary EVSE for the parking space. Only one EVSE can be marked as primary per parking space." } }, "required": [ "parkingSpaceId", "evseId", "position", "isPrimary" ], "description": "Represents how an EVSE is linked to a parking space, including its physical position and whether it's the primary EVSE for that space." } } } } }, "responses": { "204": { "description": "Given EVSEs are synchronized successfully to the Parking space" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/partner-contracts/v1.0", "method": "GET", "operationId": "partnerContractsListing", "summary": "Partner Contracts / Listing", "description": "Get all Partner Contracts", "tags": [ "resource / partner contracts" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "partnerId": { "type": "integer", "description": "Lists only Partner contracts owned by the partner with the specified system ID." }, "titleContains": { "type": "string", "description": "Lists Partner contracts whose title contains the supplied value as a substring. Matching is case-insensitive. Values shorter than 3 characters are silently ignored. Wildcard characters in the input are escaped and treated as literal characters." }, "contractType": { "type": "string", "enum": [ "revenueSharing", "paymentFacilitation" ], "description": "Lists only partner contracts with the specified contract type." }, "autoRenewal": { "type": "boolean", "description": "Lists only Partner contracts whose auto-renewal flag matches the supplied value (true or false)." }, "startDateAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted datetime. Lists only the Partner contracts whose start date is on or after this datetime." }, "endDateBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted datetime. Lists only the Partner contracts whose end date is on or before this datetime. Partner contracts without an end date (open-ended contracts) are excluded from the results." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partner contracts that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partner contracts that were last updated on and before this datetime" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partner contract records that were created on and after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partner contract records that were created on and before this datetime" }, "externalId": { "type": "string", "description": "Lists only Partner contracts with the specified external identifier value." } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-contracts/v1.0", "method": "POST", "operationId": "partnerContractCreate", "summary": "Partner Contract / Create", "description": "Create new Partner Contract", "tags": [ "resource / partner contracts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "partnerId": { "type": "integer" }, "contractType": { "type": "string", "enum": [ "revenueSharing", "paymentFacilitation" ], "description": "Indicates the business relationship model for the contract. `revenueSharing` means the operator is the supplier and remits a share to the partner. `paymentFacilitation` means the partner is the supplier and the operator acts as payment facilitator." }, "startDate": { "type": "string", "format": "date-time", "description": "The contract is effective from the first of the selected month." }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "The contract expires at the last day of the selected month. If nothing is selected, there is no expiration date." }, "autoRenewal": { "type": "boolean" }, "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "Used to store custom information, usually used for external references or metadata to the resource." }, "accessAndPermissions": { "type": "object", "properties": { "sessionsRemoteControl": { "type": "boolean", "description": "Allows the partner to start/stop session, unlock connector, trigger message, set a charging profile and get the composite schedule." }, "startReservation": { "type": "boolean", "description": "Allows the partner to make reservations." }, "stopReservation": { "type": "boolean", "description": "Allows the partner to cancel reservations." }, "resetChargePoint": { "type": "boolean", "description": "Allows the partner to reset charge points." }, "firmwareUpdate": { "type": "boolean", "description": "Allows the partner to make firmware updates to the charge points." }, "createFromTemplate": { "type": "boolean", "description": "Allows the partner to create charge points from templates." }, "changeSystemStatus": { "type": "boolean", "description": "Allows the partner to change the system status of charge points." } } }, "revenueSharing": { "type": "object", "properties": { "partnerSharePercentageAcEvse": { "type": "number", "format": "float", "minimum": 0, "maximum": 100 }, "partnerSharePercentageDcEvse": { "type": "number", "format": "float", "minimum": 0, "maximum": 100 }, "excludeConnectionFee": { "type": "boolean", "description": "If the tariff has a Connection fee, this fee would not be included in the revenue sharing with the Partner and will remain entirely for the Operator." }, "deductElectricityCost": { "type": "boolean", "description": "The cost of the electricity would first be deducted from the collected revenue and then the Revenue sharing rules will be applied." }, "reimburseForElectricityCost": { "type": "boolean", "description": "If set to true, the Partner would receive not only their share of the revenue but also a reimbursement for the cost of the electricity. The formula to calculate the amount to be received by the Partner is (Revenue - Electricity cost) x Partner percentage + Electricity cost. It could be supplied only if deductElectricityCost is set to true." }, "fixedFeePerSessionAc": { "type": "number", "format": "float", "nullable": true, "description": "Additional flat fee that is applied for every billed session and subtracted from the Partner's share of the revenue for each session on AC Charging Station." }, "fixedFeePerSessionDc": { "type": "number", "format": "float", "nullable": true, "description": "Additional flat fee that is applied for every billed session and subtracted from the Partner's share of the revenue for each session on DC Charging Station." }, "feePerKwhAc": { "type": "number", "format": "float", "nullable": true, "description": "Additional flat fee that is applied for every billed kWh and subtracted from the Partner's share of the revenue for each kWh billed on AC Charging Station." }, "feePerKwhDc": { "type": "number", "format": "float", "nullable": true, "description": "Additional flat fee that is applied for every billed kWh and subtracted from the Partner's share of the revenue for each kWh billed on DC Charging Station." }, "handlingFee": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "nullable": true, "description": "Additional percentage fee to be applied on the total amount paid by the user for the session. This fee is then subtracted from the Partner's share of the revenue." } } }, "monthlyPlatformFees": { "type": "object", "properties": { "perChargePoint": { "type": "number", "format": "float", "description": "The provided amount should be excluding VAT." }, "perAcEvse": { "type": "number", "format": "float", "description": "The provided amount should be excluding VAT." }, "perDcEvse": { "type": "number", "format": "float", "description": "The provided amount should be excluding VAT." } } }, "reimbursementFees": { "type": "object", "properties": { "perSession": { "type": "number", "format": "float", "minimum": 0, "description": "Flat fee charged for every reimbursed charging session, in the contract's currency." }, "perPeriod": { "type": "number", "format": "float", "minimum": 0, "description": "Flat fee charged for every reimbursement period, in the contract's currency." } }, "description": "Home-charging reimbursement fees configured on the contract itself and charged to the partner for reimbursed charging sessions and reimbursement periods. Only available when the home-charging reimbursement feature is enabled for the operator. All other home-charging reimbursement settings are managed on the partner resource." } }, "required": [ "title", "partnerId", "startDate" ] } } } }, "responses": { "201": { "description": "Partner Contract created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-contracts/v1.0/{partnerContract}", "method": "GET", "operationId": "partnerContractRead", "summary": "Partner Contract / Read", "description": "Get a Partner Contract", "tags": [ "resource / partner contracts" ], "parameters": { "query": { "include": { "description": "Optional related records to embed in the response. `settlementOverrides` — ⚠️ experimental. Returns the active settlement overrides of the contract, newest first. The embedded objects are not yet a stable contract and may change, including breaking changes, within `v1.0`.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "settlementOverrides" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-contracts/v1.0/{partnerContract}", "method": "PUT", "operationId": "partnerContractUpdate", "summary": "Partner Contract / Update", "description": "Update a Partner Contract", "tags": [ "resource / partner contracts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "partnerId": { "type": "integer" }, "contractType": { "type": "string", "enum": [ "revenueSharing", "paymentFacilitation" ], "description": "Indicates the business relationship model for the contract. `revenueSharing` means the operator is the supplier and remits a share to the partner. `paymentFacilitation` means the partner is the supplier and the operator acts as payment facilitator." }, "startDate": { "type": "string", "format": "date-time", "description": "The contract is effective from the first of the selected month." }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "The contract expires at the last day of the selected month. If nothing is selected, there is no expiration date." }, "autoRenewal": { "type": "boolean" }, "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "Used to store custom information, usually used for external references or metadata to the resource." }, "accessAndPermissions": { "type": "object", "properties": { "sessionsRemoteControl": { "type": "boolean", "description": "Allows the partner to start/stop session, unlock connector, trigger message, set a charging profile and get the composite schedule." }, "startReservation": { "type": "boolean", "description": "Allows the partner to make reservations." }, "stopReservation": { "type": "boolean", "description": "Allows the partner to cancel reservations." }, "resetChargePoint": { "type": "boolean", "description": "Allows the partner to reset charge points." }, "firmwareUpdate": { "type": "boolean", "description": "Allows the partner to make firmware updates to the charge points." }, "createFromTemplate": { "type": "boolean", "description": "Allows the partner to create charge points from templates." }, "changeSystemStatus": { "type": "boolean", "description": "Allows the partner to change the system status of charge points." } } }, "revenueSharing": { "type": "object", "properties": { "partnerSharePercentageAcEvse": { "type": "number", "format": "float", "minimum": 0, "maximum": 100 }, "partnerSharePercentageDcEvse": { "type": "number", "format": "float", "minimum": 0, "maximum": 100 }, "excludeConnectionFee": { "type": "boolean", "description": "If the tariff has a Connection fee, this fee would not be included in the revenue sharing with the Partner and will remain entirely for the Operator." }, "deductElectricityCost": { "type": "boolean", "description": "The cost of the electricity would first be deducted from the collected revenue and then the Revenue sharing rules will be applied." }, "reimburseForElectricityCost": { "type": "boolean", "description": "If set to true, the Partner would receive not only their share of the revenue but also a reimbursement for the cost of the electricity. The formula to calculate the amount to be received by the Partner is (Revenue - Electricity cost) x Partner percentage + Electricity cost. It could be supplied only if deductElectricityCost is set to true." }, "fixedFeePerSessionAc": { "type": "number", "format": "float", "nullable": true, "description": "Additional flat fee that is applied for every billed session and subtracted from the Partner's share of the revenue for each session on AC Charging Station." }, "fixedFeePerSessionDc": { "type": "number", "format": "float", "nullable": true, "description": "Additional flat fee that is applied for every billed session and subtracted from the Partner's share of the revenue for each session on DC Charging Station." }, "feePerKwhAc": { "type": "number", "format": "float", "nullable": true, "description": "Additional flat fee that is applied for every billed kWh and subtracted from the Partner's share of the revenue for each kWh billed on AC Charging Station." }, "feePerKwhDc": { "type": "number", "format": "float", "nullable": true, "description": "Additional flat fee that is applied for every billed kWh and subtracted from the Partner's share of the revenue for each kWh billed on DC Charging Station." }, "handlingFee": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "nullable": true, "description": "Additional percentage fee to be applied on the total amount paid by the user for the session. This fee is then subtracted from the Partner's share of the revenue." } } }, "monthlyPlatformFees": { "type": "object", "properties": { "perChargePoint": { "type": "number", "format": "float", "description": "The provided amount should be excluding VAT." }, "perAcEvse": { "type": "number", "format": "float", "description": "The provided amount should be excluding VAT." }, "perDcEvse": { "type": "number", "format": "float", "description": "The provided amount should be excluding VAT." } } }, "reimbursementFees": { "type": "object", "properties": { "perSession": { "type": "number", "format": "float", "minimum": 0, "description": "Flat fee charged for every reimbursed charging session, in the contract's currency." }, "perPeriod": { "type": "number", "format": "float", "minimum": 0, "description": "Flat fee charged for every reimbursement period, in the contract's currency." } }, "description": "Home-charging reimbursement fees configured on the contract itself and charged to the partner for reimbursed charging sessions and reimbursement periods. Only available when the home-charging reimbursement feature is enabled for the operator. All other home-charging reimbursement settings are managed on the partner resource." } }, "required": [ "title", "partnerId", "startDate" ] } } } }, "responses": { "200": { "description": "Partner Contract updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-contracts/v1.0/{partnerContract}", "method": "DELETE", "operationId": "partnerContractDelete", "summary": "Partner Contract / Delete", "description": "Delete a Partner Contract", "tags": [ "resource / partner contracts" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-contracts/v1.0/{partnerContract}", "method": "PATCH", "operationId": "partnerContractPatch", "summary": "Partner Contract / Patch", "description": "Partially update a Partner Contract. Only provided fields are updated; omitted fields retain their current values.", "tags": [ "resource / partner contracts" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "contractType": { "type": "string", "enum": [ "revenueSharing", "paymentFacilitation" ], "description": "Indicates the business relationship model for the contract. `revenueSharing` means the operator is the supplier and remits a share to the partner. `paymentFacilitation` means the partner is the supplier and the operator acts as payment facilitator." }, "startDate": { "type": "string", "format": "date-time", "description": "The contract is effective from the first of the selected month." }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "The contract expires at the last day of the selected month. If nothing is selected, there is no expiration date." }, "autoRenewal": { "type": "boolean" }, "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "Used to store custom information, usually used for external references or metadata to the resource." }, "accessAndPermissions": { "type": "object", "properties": { "sessionsRemoteControl": { "type": "boolean", "description": "Allows the partner to start/stop session, unlock connector, trigger message, set a charging profile and get the composite schedule." }, "startReservation": { "type": "boolean", "description": "Allows the partner to make reservations." }, "stopReservation": { "type": "boolean", "description": "Allows the partner to cancel reservations." }, "resetChargePoint": { "type": "boolean", "description": "Allows the partner to reset charge points." }, "firmwareUpdate": { "type": "boolean", "description": "Allows the partner to make firmware updates to the charge points." }, "createFromTemplate": { "type": "boolean", "description": "Allows the partner to create charge points from templates." }, "changeSystemStatus": { "type": "boolean", "description": "Allows the partner to change the system status of charge points." } } }, "revenueSharing": { "type": "object", "properties": { "partnerSharePercentageAcEvse": { "type": "number", "format": "float", "minimum": 0, "maximum": 100 }, "partnerSharePercentageDcEvse": { "type": "number", "format": "float", "minimum": 0, "maximum": 100 }, "excludeConnectionFee": { "type": "boolean", "description": "If the tariff has a Connection fee, this fee would not be included in the revenue sharing with the Partner and will remain entirely for the Operator." }, "deductElectricityCost": { "type": "boolean", "description": "The cost of the electricity would first be deducted from the collected revenue and then the Revenue sharing rules will be applied." }, "reimburseForElectricityCost": { "type": "boolean", "description": "If set to true, the Partner would receive not only their share of the revenue but also a reimbursement for the cost of the electricity. The formula to calculate the amount to be received by the Partner is (Revenue - Electricity cost) x Partner percentage + Electricity cost. It could be supplied only if deductElectricityCost is set to true." }, "fixedFeePerSessionAc": { "type": "number", "format": "float", "nullable": true, "description": "Additional flat fee that is applied for every billed session and subtracted from the Partner's share of the revenue for each session on AC Charging Station." }, "fixedFeePerSessionDc": { "type": "number", "format": "float", "nullable": true, "description": "Additional flat fee that is applied for every billed session and subtracted from the Partner's share of the revenue for each session on DC Charging Station." }, "feePerKwhAc": { "type": "number", "format": "float", "nullable": true, "description": "Additional flat fee that is applied for every billed kWh and subtracted from the Partner's share of the revenue for each kWh billed on AC Charging Station." }, "feePerKwhDc": { "type": "number", "format": "float", "nullable": true, "description": "Additional flat fee that is applied for every billed kWh and subtracted from the Partner's share of the revenue for each kWh billed on DC Charging Station." }, "handlingFee": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "nullable": true, "description": "Additional percentage fee to be applied on the total amount paid by the user for the session. This fee is then subtracted from the Partner's share of the revenue." } } }, "monthlyPlatformFees": { "type": "object", "properties": { "perChargePoint": { "type": "number", "format": "float", "description": "The provided amount should be excluding VAT." }, "perAcEvse": { "type": "number", "format": "float", "description": "The provided amount should be excluding VAT." }, "perDcEvse": { "type": "number", "format": "float", "description": "The provided amount should be excluding VAT." } } }, "reimbursementFees": { "type": "object", "properties": { "perSession": { "type": "number", "format": "float", "minimum": 0, "nullable": true, "description": "Flat fee charged for every reimbursed charging session, in the contract's currency. Send `null` to clear the fee; when both fees are cleared no fee entry is generated for the period. `0` is an explicit zero fee and still generates a fee entry." }, "perPeriod": { "type": "number", "format": "float", "minimum": 0, "nullable": true, "description": "Flat fee charged for every reimbursement period, in the contract's currency. Send `null` to clear the fee; when both fees are cleared no fee entry is generated for the period. `0` is an explicit zero fee and still generates a fee entry." } }, "description": "Home-charging reimbursement fees configured on the contract itself and charged to the partner for reimbursed charging sessions and reimbursement periods. Only applied when the home-charging reimbursement feature is enabled for the operator. All other home-charging reimbursement settings are managed on the partner resource." } }, "description": "All fields are optional for partial updates. Only provided fields are updated." } } } }, "responses": { "200": { "description": "Partner Contract updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-contracts/v1.0/{partnerContract}/settlement-overrides", "method": "GET", "operationId": "partnerContractSettlementOverridesListing", "summary": "Partner contract / Settlement overrides / Listing", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. List all settlement overrides of a specific partner contract, newest first. **Required permission:** `PartnerContracts.view`", "tags": [ "resource / partner contracts" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-contracts/v1.0/{partnerContract}/settlement-overrides", "method": "POST", "operationId": "partnerContractSettlementOverrideCreate", "summary": "Partner contract / Settlement override / Create", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Create a settlement override for a specific partner contract. Available only when settlement overrides are enabled for the operator owning the partner contract; otherwise the request is rejected with `412` and `errorCode` `settlement_overrides_not_enabled`. When the payload is valid but another active override on the contract already uses the requested priority, the request is rejected with `409` and `errorCode` `override_priority_taken`. Every other rejection is an ordinary `422` listing the offending properties in the `errors` map and carrying no `errorCode` — including a name already used by another active override, and including the priority conflict when the payload fails other rules as well. **Required permission:** `PartnerContracts.create`", "tags": [ "resource / partner contracts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "example": "Fleet drivers", "description": "Name of the settlement override, unique among the active overrides of the partner contract." }, "priority": { "type": "integer", "minimum": 1, "maximum": 4294967295, "example": 1, "description": "Evaluation priority of the override, unique among the active overrides of the partner contract. The lowest value that matches a session wins." }, "restriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "users_of_the_partner", "user_groups", "ad_hoc_users", "users_of_specific_partners" ], "description": "Which users of the partner contract the settlement override applies to. Allowed values: - `users_of_the_partner` - Applies to sessions of users belonging to the contract's partner. - `user_groups` - Applies to sessions of users in the listed user groups. Requires `userGroupIds`. - `ad_hoc_users` - Applies to sessions of ad hoc (unregistered) users. - `users_of_specific_partners` - Applies to sessions of users belonging to the listed partners. Requires `partnerIds`." }, "targetIds": { "type": "array", "items": { "type": "integer" }, "example": [ 12, 34 ], "description": "Identifiers of the records the override applies to, as determined by `type`: user group IDs for `user_groups` and partner IDs for `users_of_specific_partners`. Required for those two types and omitted for every other type." } }, "required": [ "type" ], "description": "Which users of the partner contract the override applies to. `type` is the discriminator and determines what `targetIds` references." }, "acPercent": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "example": 70.5, "description": "Partner share percentage applied to AC sessions matched by this override. Omit to inherit the value from the partner contract. At least one of `acPercent` and `dcPercent` must be provided." }, "dcPercent": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "example": 60, "description": "Partner share percentage applied to DC sessions matched by this override. Omit to inherit the value from the partner contract. At least one of `acPercent` and `dcPercent` must be provided." } }, "required": [ "name", "priority", "restriction" ], "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Settlement override create schema. Every property that is omitted takes its documented default; `acPercent` and `dcPercent` cannot both be omitted." } } } }, "responses": { "201": { "description": "Settlement override created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request conflicts with the current state of the partner contract: another active override already uses the requested priority. The payload itself is valid, so retrying with a free priority succeeds." }, "412": { "description": "The partner contract does not meet a precondition of the action: settlement overrides are not enabled for the operator owning it. Enabling them in the admin makes the action available." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-contracts/v1.0/{partnerContract}/settlement-overrides/{settlementOverride}", "method": "GET", "operationId": "partnerContractSettlementOverrideRead", "summary": "Partner contract / Settlement override / Read", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Read a single settlement override of a specific partner contract. **Required permission:** `PartnerContracts.view`", "tags": [ "resource / partner contracts" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-contracts/v1.0/{partnerContract}/settlement-overrides/{settlementOverride}", "method": "DELETE", "operationId": "partnerContractSettlementOverrideDelete", "summary": "Partner contract / Settlement override / Delete", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Delete a settlement override from a specific partner contract. Available only when settlement overrides are enabled for the operator owning the partner contract; otherwise the request is rejected with `412` and `errorCode` `settlement_overrides_not_enabled`. **Required permission:** `PartnerContracts.delete`", "tags": [ "resource / partner contracts" ], "responses": { "204": { "description": "Settlement override deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "412": { "description": "The partner contract does not meet a precondition of the action: settlement overrides are not enabled for the operator owning it. Enabling them in the admin makes the action available." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-contracts/v1.0/{partnerContract}/settlement-overrides/{settlementOverride}", "method": "PATCH", "operationId": "partnerContractSettlementOverrideUpdate", "summary": "Partner contract / Settlement override / Update", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Update a settlement override of a specific partner contract. Omitted properties keep their current value; `restriction` is replaced as a whole when present. Available only when settlement overrides are enabled for the operator owning the partner contract; otherwise the request is rejected with `412` and `errorCode` `settlement_overrides_not_enabled`. When the payload is valid but another active override on the contract already uses the requested priority, the request is rejected with `409` and `errorCode` `override_priority_taken`. Every other rejection is an ordinary `422` listing the offending properties in the `errors` map and carrying no `errorCode` — including a name already used by another active override, and including the priority conflict when the payload fails other rules as well. **Required permission:** `PartnerContracts.update`", "tags": [ "resource / partner contracts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "example": "Fleet drivers", "description": "Name of the settlement override, unique among the active overrides of the partner contract." }, "priority": { "type": "integer", "minimum": 1, "maximum": 4294967295, "example": 1, "description": "Evaluation priority of the override, unique among the active overrides of the partner contract. The lowest value that matches a session wins." }, "restriction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "users_of_the_partner", "user_groups", "ad_hoc_users", "users_of_specific_partners" ], "description": "Which users of the partner contract the settlement override applies to. Allowed values: - `users_of_the_partner` - Applies to sessions of users belonging to the contract's partner. - `user_groups` - Applies to sessions of users in the listed user groups. Requires `userGroupIds`. - `ad_hoc_users` - Applies to sessions of ad hoc (unregistered) users. - `users_of_specific_partners` - Applies to sessions of users belonging to the listed partners. Requires `partnerIds`." }, "targetIds": { "type": "array", "items": { "type": "integer" }, "example": [ 12, 34 ], "description": "Identifiers of the records the override applies to, as determined by `type`: user group IDs for `user_groups` and partner IDs for `users_of_specific_partners`. Required for those two types and omitted for every other type." } }, "required": [ "type" ], "description": "Which users of the partner contract the override applies to. `type` is the discriminator and determines what `targetIds` references." }, "acPercent": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "example": 70.5, "nullable": true, "description": "Partner share percentage applied to AC sessions matched by this override. Send `null` to inherit the value from the partner contract. `acPercent` and `dcPercent` cannot both end up inherited." }, "dcPercent": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "example": 60, "nullable": true, "description": "Partner share percentage applied to DC sessions matched by this override. Send `null` to inherit the value from the partner contract. `acPercent` and `dcPercent` cannot both end up inherited." } }, "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Settlement override update schema. Omitted properties keep their current value; `restriction` is replaced as a whole when present." } } } }, "responses": { "200": { "description": "Settlement override updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request conflicts with the current state of the partner contract: another active override already uses the requested priority. The payload itself is valid, so retrying with a free priority succeeds." }, "412": { "description": "The partner contract does not meet a precondition of the action: settlement overrides are not enabled for the operator owning it. Enabling them in the admin makes the action available." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-expenses/v1.0", "method": "GET", "operationId": "expensesListingDeprecated", "summary": "Expenses / Listing", "description": "Get all expenses", "deprecated": true, "tags": [ "resource / revenues & expenses" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "partnerId": { "type": "string", "format": "integer", "description": "Only list expenses associated with a certain partner" }, "dateFrom": { "type": "string", "format": "date-time", "description": "Date from based on created at" }, "dateTo": { "type": "string", "format": "date-time", "description": "Date to based on created at" }, "origin": { "type": "string", "enum": [ "platform-fee-emsp", "platform-fee-cpo", "user-custom-fee", "session-emsp" ], "description": "Only list revenue by origin" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR", "description": "3-letter currency code (ISO 4217). Only list expenses by currency" } } } }, "withBreakdown": { "description": "A detailed information about the expense \"platform-fee-cpo\" is returned, based on the contract details.", "type": "boolean", "default": false }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/partner-expenses/v1.1", "method": "GET", "operationId": "expensesListing", "summary": "Expenses / Listing", "description": "This endpoint is deprecated. Use v1.2 for tax-inclusive amount breakdowns. Get all expenses", "deprecated": true, "tags": [ "resource / revenues & expenses" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "partnerId": { "type": "string", "format": "integer", "description": "Only list expenses associated with a certain partner" }, "settlementReportId": { "type": "string", "format": "integer", "description": "Only list expenses associated with a certain settlement report" }, "dateBefore": { "type": "string", "format": "date-time" }, "dateAfter": { "type": "string", "format": "date-time" }, "origin": { "type": "string", "enum": [ "platform-fee-emsp", "platform-fee-cpo", "private-evse-access-fee", "user-custom-fee", "session-emsp" ], "description": "Only list expenses by origin" }, "currencyCode": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR", "description": "3-letter currency code (ISO 4217). Only list expenses by currency" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the expense records that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the expense records that were last updated on and before this datetime" } } } }, "withBreakdown": { "description": "A detailed information about the expense \"platform-fee-cpo\" is returned, based on the contract details.", "type": "boolean", "default": false }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/partner-expenses/v1.2", "method": "GET", "operationId": "expensesV1_2Listing", "summary": "Expenses / Listing", "description": "Get all expenses", "tags": [ "resource / revenues & expenses" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "partnerId": { "type": "string", "format": "integer", "description": "Only list expenses associated with a certain partner" }, "settlementReportId": { "type": "string", "format": "integer", "description": "Only list expenses associated with a certain settlement report" }, "origin": { "type": "string", "enum": [ "platform-fee-emsp", "platform-fee-cpo-flat", "private-evse-access-fee", "user-custom-fee", "session-emsp" ], "description": "Only list expenses by origin" }, "currencyCode": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR", "description": "3-letter currency code (ISO 4217). Only list expenses by currency" }, "dateBefore": { "type": "string", "format": "date-time" }, "dateAfter": { "type": "string", "format": "date-time" }, "chargePointId": { "type": "string", "format": "integer", "description": "Only list expenses associated with a certain charge point" }, "locationId": { "type": "string", "format": "integer", "description": "Only list expenses associated with a certain location" }, "partnerContractId": { "type": "string", "format": "integer", "description": "Only list expenses associated with a certain partner contract" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the expense records that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the expense records that were last updated on and before this datetime" } } } }, "withBreakdown": { "description": "A detailed information about the expense \"platform-fee-cpo\" is returned, based on the contract details.", "type": "boolean", "default": false }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/partner-invite-access-policies/v1.0", "method": "GET", "operationId": "partnerInviteAccessPoliciesListing", "summary": "Partner invite access policies / listing", "description": "Get all partner invite access policies", "tags": [ "resource / partner invite access policies" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "partnerId": { "type": "string", "format": "integer", "description": "Return policies accessible by a specific partner — matches policies where partner access type is `none` as well as policies where the partner IDs list includes the given partner." }, "includeSharedChargePoints": { "type": "string", "format": "boolean", "description": "Filter by whether shared charge points are included." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the access policies that were last updated on and after this datetime." }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the access policies that were last updated on and before this datetime." } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invite-access-policies/v1.0", "method": "POST", "operationId": "partnerInviteAccessPolicyCreate", "summary": "Partner invite access policy / create", "description": "Create a new partner invite access policy", "tags": [ "resource / partner invite access policies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "description": "The operator ID. Required for global admin tokens. Defaults to the token's operator for operator-scoped tokens." }, "name": { "type": "string", "maxLength": 255, "description": "Name of the access policy." }, "partnerAccess": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow" ], "description": "Controls which partners can use the access policy when creating invites. - `none` — no partner restriction; any partner under the operator can use the policy, including future partners - `allow` — only the specified partners can use the policy" }, "partnerIds": { "type": "array", "items": { "type": "integer" }, "description": "The IDs of partners who can use the policy. Required when `type` is `allow`, prohibited when `type` is `none`. In responses the field is present only when `type` is `allow`." } }, "required": [ "type" ], "description": "Controls which partners can use this policy when creating invites. - `none` — no partner restriction; any partner under the operator can use the policy, including future partners - `allow` — only the specified partners (`partnerIds` is required)" }, "restrictions": { "type": "object", "properties": { "locations": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "Restriction type. - `none` — no restriction for this target type - `allow` — allow only the listed target IDs - `deny` — deny the listed target IDs" }, "locationIds": { "type": "array", "items": { "type": "integer" }, "description": "Required when `type` is `allow` or `deny`. When `type` is `none` the list is not needed — an empty list is accepted and ignored, a non-empty list is rejected. An empty `allow` list represents no accessible charge points." } }, "required": [ "type" ], "description": "Controls access to the partner's charge points by the location they belong to. `none` means no location restriction, `allow` limits access to charge points at the listed locations, and `deny` excludes charge points at the listed locations." }, "chargePoints": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "Restriction type. - `none` — no restriction for this target type - `allow` — allow only the listed target IDs - `deny` — deny the listed target IDs" }, "chargePointIds": { "type": "array", "items": { "type": "integer" }, "description": "Required when `type` is `allow` or `deny`. When `type` is `none` the list is not needed — an empty list is accepted and ignored, a non-empty list is rejected." } }, "required": [ "type" ], "description": "Controls access to the partner's charge points by explicit charge point IDs. `none` means no charge point ID restriction, `allow` limits access to the listed charge points, and `deny` excludes the listed charge points." }, "locationTags": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "Restriction type. - `none` — no restriction for this target type - `allow` — allow only the listed target IDs - `deny` — deny the listed target IDs" }, "locationTagIds": { "type": "array", "items": { "type": "integer" }, "description": "Required when `type` is `allow` or `deny`. When `type` is `none` the list is not needed — an empty list is accepted and ignored, a non-empty list is rejected." } }, "required": [ "type" ], "description": "Controls access to the partner's charge points by the tags assigned to their locations. `none` means no location tag restriction, `allow` limits access to charge points at locations carrying the listed tags, and `deny` excludes charge points at locations carrying the listed tags." }, "chargePointTags": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "Restriction type. - `none` — no restriction for this target type - `allow` — allow only the listed target IDs - `deny` — deny the listed target IDs" }, "chargePointTagIds": { "type": "array", "items": { "type": "integer" }, "description": "Required when `type` is `allow` or `deny`. When `type` is `none` the list is not needed — an empty list is accepted and ignored, a non-empty list is rejected." } }, "required": [ "type" ], "description": "Controls access to the partner's charge points by the tags assigned to the charge points. `none` means no charge point tag restriction, `allow` limits access to charge points carrying the listed tags, and `deny` excludes charge points carrying the listed tags." } }, "description": "Defines which of the partner's charge points invited users can access. Each sub-restriction is optional on input — an omitted sub-restriction is treated as `none`. At most one sub-restriction can use `allow` or `deny`; providing more than one active sub-restriction is a validation error. An empty object, or all sub-restrictions set to `none`, grants access to all of the partner's charge points. To grant access to no charge points, set `locations.type` to `allow` with an empty `locationIds` list. Location tag restrictions use `locationTagIds`; charge point tag restrictions use `chargePointTagIds`. In responses all four sub-restrictions are always present." }, "includeSharedChargePoints": { "type": "boolean", "default": false, "description": "When `true`, invited users also have access to charge points of other partners that are shared with the inviting partner." } }, "required": [ "name", "partnerAccess" ], "description": "Partner invite access policy" } } } }, "responses": { "201": { "description": "Partner invite access policy created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invite-access-policies/v1.0/{partnerInviteAccessPolicy}", "method": "GET", "operationId": "partnerInviteAccessPolicyRead", "summary": "Partner invite access policy / read", "description": "Get a partner invite access policy", "tags": [ "resource / partner invite access policies" ], "parameters": { "path": { "partnerInviteAccessPolicy": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invite-access-policies/v1.0/{partnerInviteAccessPolicy}", "method": "DELETE", "operationId": "partnerInviteAccessPolicyDelete", "summary": "Partner invite access policy / delete", "description": "Delete a partner invite access policy. Policies assigned to partner invites cannot be deleted and return a 422 validation error. The default access policy (\"Full private access\") cannot be deleted.", "tags": [ "resource / partner invite access policies" ], "parameters": { "path": { "partnerInviteAccessPolicy": { "type": "integer", "required": true } } }, "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invite-access-policies/v1.0/{partnerInviteAccessPolicy}", "method": "PATCH", "operationId": "partnerInviteAccessPolicyUpdate", "summary": "Partner invite access policy / update", "description": "Update a partner invite access policy. Only provided fields are updated; nested `partnerAccess` and `restrictions` objects are replaced entirely when provided. Updating `partnerAccess` returns 409 Conflict when the new partner scope would no longer cover partners whose existing invites already reference the policy. Detach those invites or keep those partners in scope first. The default access policy (\"Full private access\") cannot be updated.", "tags": [ "resource / partner invite access policies" ], "parameters": { "path": { "partnerInviteAccessPolicy": { "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "partnerAccess": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow" ], "description": "Controls which partners can use the access policy when creating invites. - `none` — no partner restriction; any partner under the operator can use the policy, including future partners - `allow` — only the specified partners can use the policy" }, "partnerIds": { "type": "array", "items": { "type": "integer" }, "description": "The IDs of partners who can use the policy. Required when `type` is `allow`, prohibited when `type` is `none`. In responses the field is present only when `type` is `allow`." } }, "required": [ "type" ], "description": "Controls which partners can use this policy when creating invites. - `none` — no partner restriction; any partner under the operator can use the policy, including future partners - `allow` — only the specified partners (`partnerIds` is required)" }, "restrictions": { "type": "object", "properties": { "locations": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "Restriction type. - `none` — no restriction for this target type - `allow` — allow only the listed target IDs - `deny` — deny the listed target IDs" }, "locationIds": { "type": "array", "items": { "type": "integer" }, "description": "Required when `type` is `allow` or `deny`. When `type` is `none` the list is not needed — an empty list is accepted and ignored, a non-empty list is rejected. An empty `allow` list represents no accessible charge points." } }, "required": [ "type" ], "description": "Controls access to the partner's charge points by the location they belong to. `none` means no location restriction, `allow` limits access to charge points at the listed locations, and `deny` excludes charge points at the listed locations." }, "chargePoints": { "type": "object", "properties": { "type": {}, "chargePointIds": { "type": "array", "items": { "type": "integer" }, "description": "Required when `type` is `allow` or `deny`. When `type` is `none` the list is not needed — an empty list is accepted and ignored, a non-empty list is rejected." } }, "required": [ "type" ], "description": "Controls access to the partner's charge points by explicit charge point IDs. `none` means no charge point ID restriction, `allow` limits access to the listed charge points, and `deny` excludes the listed charge points." }, "locationTags": { "type": "object", "properties": { "type": {}, "locationTagIds": { "type": "array", "items": { "type": "integer" }, "description": "Required when `type` is `allow` or `deny`. When `type` is `none` the list is not needed — an empty list is accepted and ignored, a non-empty list is rejected." } }, "required": [ "type" ], "description": "Controls access to the partner's charge points by the tags assigned to their locations. `none` means no location tag restriction, `allow` limits access to charge points at locations carrying the listed tags, and `deny` excludes charge points at locations carrying the listed tags." }, "chargePointTags": { "type": "object", "properties": { "type": {}, "chargePointTagIds": { "type": "array", "items": { "type": "integer" }, "description": "Required when `type` is `allow` or `deny`. When `type` is `none` the list is not needed — an empty list is accepted and ignored, a non-empty list is rejected." } }, "required": [ "type" ], "description": "Controls access to the partner's charge points by the tags assigned to the charge points. `none` means no charge point tag restriction, `allow` limits access to charge points carrying the listed tags, and `deny` excludes charge points carrying the listed tags." } }, "description": "Defines which of the partner's charge points invited users can access. Each sub-restriction is optional on input — an omitted sub-restriction is treated as `none`. At most one sub-restriction can use `allow` or `deny`; providing more than one active sub-restriction is a validation error. An empty object, or all sub-restrictions set to `none`, grants access to all of the partner's charge points. To grant access to no charge points, set `locations.type` to `allow` with an empty `locationIds` list. Location tag restrictions use `locationTagIds`; charge point tag restrictions use `chargePointTagIds`. In responses all four sub-restrictions are always present." }, "includeSharedChargePoints": { "type": "boolean" } }, "description": "Partner invite access policy update. All fields are optional — only provided fields are updated. The `operatorId` field is immutable after creation and must not be provided. Nested object replacement: when `partnerAccess` or `restrictions` is provided, the entire object is replaced — not deep-merged. Previously stored IDs are removed as part of the replacement when the new `type` does not use them. `partnerAccess` updates return 409 Conflict when the replacement would no longer cover partners whose existing invites already reference the policy. The default access policy (\"Full private access\") cannot be updated and returns 422." } } } }, "responses": { "200": { "description": "Partner invite access policy updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invite-corporate-billing-policies/v1.0", "method": "GET", "operationId": "partnerInviteCorporateBillingPoliciesListing", "summary": "Partner invite corporate billing policies / Listing", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Get all partner invite corporate billing policies.", "tags": [ "resource / partner invite corporate billing policies" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "partnerId": { "type": "integer" }, "isActive": { "type": "boolean" }, "coverageType": { "type": "string", "enum": [ "full_coverage", "limited_coverage" ], "description": "Corporate billing policy coverage type: - **full_coverage**: The policy covers eligible session costs without tariff thresholds - **limited_coverage**: The policy covers eligible session costs only within configured limits" } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invite-corporate-billing-policies/v1.0", "method": "POST", "operationId": "partnerInviteCorporateBillingPolicyCreate", "summary": "Partner invite corporate billing policy / Create", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Create a partner invite corporate billing policy.", "tags": [ "resource / partner invite corporate billing policies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partnerId": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "coverageType": { "type": "string", "enum": [ "full_coverage", "limited_coverage" ], "description": "Corporate billing policy coverage type: - **full_coverage**: The policy covers eligible session costs without tariff thresholds - **limited_coverage**: The policy covers eligible session costs only within configured limits" }, "individualSpendingLimit": { "type": "number", "format": "float", "minimum": 0, "description": "Authorization-time spending threshold for a driver's accumulated corporate-billed cost on the corporate account within the billing period. Once the accumulated cost reaches the limit, the policy stops covering that driver's subsequent sessions until the period resets. The session in which the limit is reached is still covered in full. Omit this property to set no per-driver spending limit." }, "externalId": { "type": "string", "maxLength": 255, "description": "An optional external identifier for integration purposes" }, "restrictions": { "type": "object", "properties": { "partner": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "own_only", "allow", "deny" ], "description": "Partner restriction mode: - **none**: No partner restriction applies. - **own_only**: Only the operator's own charge points are eligible. - **allow**: Only listed partner IDs are eligible. - **deny**: Listed partner IDs are excluded." }, "partnerIds": { "type": "array", "items": { "type": "integer" }, "description": "Partner IDs used by list-based partner restriction modes." } }, "required": [ "type" ], "description": "Constrains coverage by partner. `partnerIds` is interpreted together with the selected `type`; for list-based modes it contains the partner IDs to allow or deny." }, "country": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "Restriction mode: - **none**: No restriction applies. - **allow**: Only listed values are eligible. - **deny**: Listed values are excluded." }, "countries": { "type": "array", "items": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "description": "Country codes used by list-based country restriction modes." } }, "required": [ "type" ], "description": "Constrains coverage by country. `countries` is interpreted together with the selected `type`; for list-based modes it contains the countries to allow or deny." }, "location": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "Restriction mode: - **none**: No restriction applies. - **allow**: Only listed values are eligible. - **deny**: Listed values are excluded." }, "locationIds": { "type": "array", "items": { "type": "integer" }, "description": "Location IDs used by list-based location restriction modes." } }, "required": [ "type" ], "description": "Constrains coverage by location. `locationIds` is interpreted together with the selected `type`; for list-based modes it contains the location IDs to allow or deny." }, "locationTag": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "Restriction mode: - **none**: No restriction applies. - **allow**: Only listed values are eligible. - **deny**: Listed values are excluded." }, "locationTagIds": { "type": "array", "items": { "type": "integer" }, "description": "Location tag IDs used by list-based location tag restriction modes." } }, "required": [ "type" ], "description": "Constrains coverage by location tag. `locationTagIds` is interpreted together with the selected `type`; for list-based modes it contains the location tag IDs to allow or deny." }, "roaming": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "deny_all", "allow", "deny" ], "description": "Roaming restriction mode: - **none**: No roaming restriction applies. - **deny_all**: Roaming sessions are not eligible. - **allow**: Only listed roaming partners are eligible. - **deny**: Listed roaming partners are excluded." }, "roamingOperatorIds": { "type": "array", "items": { "type": "integer" }, "description": "Roaming operator IDs used by list-based roaming restriction modes." } }, "required": [ "type" ], "description": "Constrains coverage by roaming operator. `roamingOperatorIds` is interpreted together with the selected `type`; for list-based modes it contains the roaming operator IDs to allow or deny." } }, "required": [ "partner", "country", "location", "locationTag", "roaming" ], "description": "Restrictions that determine whether a session is eligible for corporate billing. Allow-list modes cover only the listed values, deny-list modes withhold coverage for the listed values, and no-restriction modes leave that dimension unrestricted. A session must pass every restriction dimension; when any dimension excludes it, corporate billing is withheld and the policy does not cover the session." }, "tariffThresholds": { "type": "object", "properties": { "energy": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "idleTime": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "connection": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "chargingTime": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." } }, "description": "Per-component limits on the costs the policy covers. Costs above the configured limits are the driver's responsibility. Omitted limit fields mean that the policy has no limit for that dimension." }, "overallCostCap": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the overall cost cap applies." }, "maxCostPerKwh": { "type": "number", "format": "float", "minimum": 0, "description": "Required when `enabled` is `true`." } }, "required": [ "enabled" ], "description": "Caps the amount the policy covers at `maxCostPerKwh` for each kWh charged. When the covered cost exceeds `maxCostPerKwh` multiplied by the energy charged, coverage is reduced to that maximum and the remainder is the driver's responsibility." }, "chargerTypeConfig": { "type": "object", "properties": { "ac": { "type": "object", "properties": { "coverageType": { "type": "string", "enum": [ "full_coverage", "limited_coverage", "not_covered" ], "description": "Charger type coverage type: - **full_coverage**: The policy covers eligible costs for this charger type without tariff thresholds - **limited_coverage**: The policy covers eligible costs for this charger type only within configured limits - **not_covered**: The policy does not cover sessions on this charger type" }, "tariffThresholds": { "type": "object", "properties": { "energy": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "idleTime": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "connection": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "chargingTime": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." } }, "description": "Per-component limits on the costs the policy covers. Costs above the configured limits are the driver's responsibility. Omitted limit fields mean that the policy has no limit for that dimension." }, "overallCostCap": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the overall cost cap applies." }, "maxCostPerKwh": { "type": "number", "format": "float", "minimum": 0, "description": "Required when `enabled` is `true`." } }, "required": [ "enabled" ], "description": "Caps the amount the policy covers at `maxCostPerKwh` for each kWh charged. When the covered cost exceeds `maxCostPerKwh` multiplied by the energy charged, coverage is reduced to that maximum and the remainder is the driver's responsibility." } }, "required": [ "coverageType" ], "description": "Coverage settings for one charger type. `coverageType` defines whether eligible sessions on this charger type are fully covered, covered only within configured limits, or not covered. The nested limits are used only for limited coverage." }, "dc": { "type": "object", "properties": { "coverageType": { "type": "string", "enum": [ "full_coverage", "limited_coverage", "not_covered" ], "description": "Charger type coverage type: - **full_coverage**: The policy covers eligible costs for this charger type without tariff thresholds - **limited_coverage**: The policy covers eligible costs for this charger type only within configured limits - **not_covered**: The policy does not cover sessions on this charger type" }, "tariffThresholds": { "type": "object", "properties": { "energy": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "idleTime": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "connection": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "chargingTime": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." } }, "description": "Per-component limits on the costs the policy covers. Costs above the configured limits are the driver's responsibility. Omitted limit fields mean that the policy has no limit for that dimension." }, "overallCostCap": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the overall cost cap applies." }, "maxCostPerKwh": { "type": "number", "format": "float", "minimum": 0, "description": "Required when `enabled` is `true`." } }, "required": [ "enabled" ], "description": "Caps the amount the policy covers at `maxCostPerKwh` for each kWh charged. When the covered cost exceeds `maxCostPerKwh` multiplied by the energy charged, coverage is reduced to that maximum and the remainder is the driver's responsibility." } }, "required": [ "coverageType" ], "description": "Coverage settings for one charger type. `coverageType` defines whether eligible sessions on this charger type are fully covered, covered only within configured limits, or not covered. The nested limits are used only for limited coverage." } }, "required": [ "ac", "dc" ], "description": "Defines separate AC and DC coverage. Each charger type has its own coverage type for full coverage, limited coverage, or no coverage. Both `ac` and `dc` are required when this object is provided. When `chargerTypeConfig` is present, coverage is resolved per charger type from this object, and the top-level `coverageType`, `tariffThresholds`, and `overallCostCap` are ignored." } }, "required": [ "partnerId", "name", "coverageType" ], "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Partner invite corporate billing policy create schema. The policy defines when corporate billing covers a driver's session costs and which limits, restrictions, and charger-type rules apply." } } } }, "responses": { "201": { "description": "Created" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invite-corporate-billing-policies/v1.0/{corporateBillingPolicy}", "method": "GET", "operationId": "partnerInviteCorporateBillingPolicyRead", "summary": "Partner invite corporate billing policy / Read", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Get a single partner invite corporate billing policy.", "tags": [ "resource / partner invite corporate billing policies" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invite-corporate-billing-policies/v1.0/{corporateBillingPolicy}", "method": "DELETE", "operationId": "partnerInviteCorporateBillingPolicyDelete", "summary": "Partner invite corporate billing policy / Delete", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Delete a partner invite corporate billing policy. Deletion is rejected while the policy is assigned to pending or accepted partner invites.", "tags": [ "resource / partner invite corporate billing policies" ], "responses": { "204": { "description": "No content" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invite-corporate-billing-policies/v1.0/{corporateBillingPolicy}", "method": "PATCH", "operationId": "partnerInviteCorporateBillingPolicyUpdate", "summary": "Partner invite corporate billing policy / Update", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Update a partner invite corporate billing policy.", "tags": [ "resource / partner invite corporate billing policies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "coverageType": { "type": "string", "enum": [ "full_coverage", "limited_coverage" ], "description": "Corporate billing policy coverage type: - **full_coverage**: The policy covers eligible session costs without tariff thresholds - **limited_coverage**: The policy covers eligible session costs only within configured limits" }, "individualSpendingLimit": { "type": "number", "format": "float", "minimum": 0, "nullable": true, "description": "Authorization-time spending threshold for a driver's accumulated corporate-billed cost on the corporate account within the billing period. Once the accumulated cost reaches the limit, the policy stops covering that driver's subsequent sessions until the period resets. The session in which the limit is reached is still covered in full. Set to `null` to remove the per-driver spending limit." }, "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "An optional external identifier for integration purposes" }, "restrictions": { "type": "object", "properties": { "partner": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "own_only", "allow", "deny" ], "description": "Partner restriction mode: - **none**: No partner restriction applies. - **own_only**: Only the operator's own charge points are eligible. - **allow**: Only listed partner IDs are eligible. - **deny**: Listed partner IDs are excluded." }, "partnerIds": { "type": "array", "items": { "type": "integer" }, "description": "Partner IDs used by list-based partner restriction modes." } }, "required": [ "type" ], "description": "Constrains coverage by partner. `partnerIds` is interpreted together with the selected `type`; for list-based modes it contains the partner IDs to allow or deny." }, "country": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "Restriction mode: - **none**: No restriction applies. - **allow**: Only listed values are eligible. - **deny**: Listed values are excluded." }, "countries": { "type": "array", "items": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "description": "Country codes used by list-based country restriction modes." } }, "required": [ "type" ], "description": "Constrains coverage by country. `countries` is interpreted together with the selected `type`; for list-based modes it contains the countries to allow or deny." }, "location": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "Restriction mode: - **none**: No restriction applies. - **allow**: Only listed values are eligible. - **deny**: Listed values are excluded." }, "locationIds": { "type": "array", "items": { "type": "integer" }, "description": "Location IDs used by list-based location restriction modes." } }, "required": [ "type" ], "description": "Constrains coverage by location. `locationIds` is interpreted together with the selected `type`; for list-based modes it contains the location IDs to allow or deny." }, "locationTag": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow", "deny" ], "description": "Restriction mode: - **none**: No restriction applies. - **allow**: Only listed values are eligible. - **deny**: Listed values are excluded." }, "locationTagIds": { "type": "array", "items": { "type": "integer" }, "description": "Location tag IDs used by list-based location tag restriction modes." } }, "required": [ "type" ], "description": "Constrains coverage by location tag. `locationTagIds` is interpreted together with the selected `type`; for list-based modes it contains the location tag IDs to allow or deny." }, "roaming": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "deny_all", "allow", "deny" ], "description": "Roaming restriction mode: - **none**: No roaming restriction applies. - **deny_all**: Roaming sessions are not eligible. - **allow**: Only listed roaming partners are eligible. - **deny**: Listed roaming partners are excluded." }, "roamingOperatorIds": { "type": "array", "items": { "type": "integer" }, "description": "Roaming operator IDs used by list-based roaming restriction modes." } }, "required": [ "type" ], "description": "Constrains coverage by roaming operator. `roamingOperatorIds` is interpreted together with the selected `type`; for list-based modes it contains the roaming operator IDs to allow or deny." } }, "required": [ "partner", "country", "location", "locationTag", "roaming" ], "nullable": true }, "tariffThresholds": { "type": "object", "properties": { "energy": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "idleTime": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "connection": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "chargingTime": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." } }, "nullable": true, "description": "Per-component limits on the costs the policy covers. Costs above the configured limits are the driver's responsibility. Omitted limit fields mean that the policy has no limit for that dimension." }, "overallCostCap": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the overall cost cap applies." }, "maxCostPerKwh": { "type": "number", "format": "float", "minimum": 0, "description": "Required when `enabled` is `true`." } }, "required": [ "enabled" ], "nullable": true, "description": "Caps the amount the policy covers at `maxCostPerKwh` for each kWh charged. When the covered cost exceeds `maxCostPerKwh` multiplied by the energy charged, coverage is reduced to that maximum and the remainder is the driver's responsibility." }, "chargerTypeConfig": { "type": "object", "properties": { "ac": { "type": "object", "properties": { "coverageType": { "type": "string", "enum": [ "full_coverage", "limited_coverage", "not_covered" ], "description": "Charger type coverage type: - **full_coverage**: The policy covers eligible costs for this charger type without tariff thresholds - **limited_coverage**: The policy covers eligible costs for this charger type only within configured limits - **not_covered**: The policy does not cover sessions on this charger type" }, "tariffThresholds": { "type": "object", "properties": { "energy": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "idleTime": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "connection": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "chargingTime": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." } }, "description": "Per-component limits on the costs the policy covers. Costs above the configured limits are the driver's responsibility. Omitted limit fields mean that the policy has no limit for that dimension." }, "overallCostCap": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the overall cost cap applies." }, "maxCostPerKwh": { "type": "number", "format": "float", "minimum": 0, "description": "Required when `enabled` is `true`." } }, "required": [ "enabled" ], "description": "Caps the amount the policy covers at `maxCostPerKwh` for each kWh charged. When the covered cost exceeds `maxCostPerKwh` multiplied by the energy charged, coverage is reduced to that maximum and the remainder is the driver's responsibility." } }, "required": [ "coverageType" ], "description": "Coverage settings for one charger type. `coverageType` defines whether eligible sessions on this charger type are fully covered, covered only within configured limits, or not covered. The nested limits are used only for limited coverage." }, "dc": { "type": "object", "properties": { "coverageType": { "type": "string", "enum": [ "full_coverage", "limited_coverage", "not_covered" ], "description": "Charger type coverage type: - **full_coverage**: The policy covers eligible costs for this charger type without tariff thresholds - **limited_coverage**: The policy covers eligible costs for this charger type only within configured limits - **not_covered**: The policy does not cover sessions on this charger type" }, "tariffThresholds": { "type": "object", "properties": { "energy": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "idleTime": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "connection": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." }, "chargingTime": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the policy covers this tariff component." }, "maxUnitPrice": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support unit-price caps." }, "maxQuantity": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to energy, idleTime, and chargingTime components only. The connection component does not support quantity caps." }, "maxAmount": { "type": "number", "format": "float", "minimum": 0, "description": "Applies to the connection component only. Energy, idleTime, and chargingTime components do not support flat amount caps." } }, "required": [ "enabled" ], "description": "A limit for one tariff component. When the component is disabled, the policy does not cover that component and the driver pays it in full. Omitted limit fields mean that the policy has no limit for that dimension." } }, "description": "Per-component limits on the costs the policy covers. Costs above the configured limits are the driver's responsibility. Omitted limit fields mean that the policy has no limit for that dimension." }, "overallCostCap": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the overall cost cap applies." }, "maxCostPerKwh": { "type": "number", "format": "float", "minimum": 0, "description": "Required when `enabled` is `true`." } }, "required": [ "enabled" ], "description": "Caps the amount the policy covers at `maxCostPerKwh` for each kWh charged. When the covered cost exceeds `maxCostPerKwh` multiplied by the energy charged, coverage is reduced to that maximum and the remainder is the driver's responsibility." } }, "required": [ "coverageType" ], "description": "Coverage settings for one charger type. `coverageType` defines whether eligible sessions on this charger type are fully covered, covered only within configured limits, or not covered. The nested limits are used only for limited coverage." } }, "required": [ "ac", "dc" ], "nullable": true, "description": "Defines separate AC and DC coverage. Each charger type has its own coverage type for full coverage, limited coverage, or no coverage. Both `ac` and `dc` are required when this object is provided. When `chargerTypeConfig` is present, coverage is resolved per charger type from this object, and the top-level `coverageType`, `tariffThresholds`, and `overallCostCap` are ignored." } }, "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Partner invite corporate billing policy update schema. The policy defines when corporate billing covers a driver's session costs and which limits, restrictions, and charger-type rules apply." } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invite-corporate-billing-policy-snapshots/v1.0/{corporateBillingPolicySnapshot}", "method": "GET", "operationId": "partnerInviteCorporateBillingPolicySnapshotRead", "summary": "Partner invite corporate billing policy snapshot / Read", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Get a single partner invite corporate billing policy snapshot.", "tags": [ "resource / partner invite corporate billing policy snapshots" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invites/v1.0", "method": "GET", "operationId": "partnerInvitesListing", "summary": "Partner Invites / Listing", "description": "**This endpoint is deprecated. Use `resources/partner-invites/v2.0` instead.** Get all partner invites", "deprecated": true, "tags": [ "resource / partner invites" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "partnerId": { "type": "string", "format": "integer", "description": "Only list expenses associated with a certain partner" }, "status": { "type": "string", "enum": [ "pending", "sent", "accepted" ], "description": "Only list invites in this status" }, "createdFrom": { "type": "string", "format": "date-time" }, "createdTo": { "type": "string", "format": "date-time" }, "userId": { "type": "string", "format": "integer", "description": "Only list partner invite records accepted by a certain user" }, "inviteEmail": { "type": "string", "format": "email", "description": "Only list partner invite records sent to a particular email address" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partner invites that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partner invites that were last updated on and before this datetime" }, "acceptedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partner invites that were accepted on and after this datetime" }, "acceptedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partner invites that were accepted on and before this datetime" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invites/v1.0", "method": "POST", "operationId": "partnerInviteCreate", "summary": "Partner Invite / Create", "description": "**This endpoint is deprecated. Use `resources/partner-invites/v2.0` instead.** Create new invite", "deprecated": true, "tags": [ "resource / partner invites" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partnerId": { "type": "integer" }, "sendViaEmail": { "type": "boolean" }, "email": { "type": "string", "format": "email", "description": "Required if `sendViaEmail` is true (default). Optional when `sendViaEmail` is false; when provided, the invite is linked to the matching user without dispatching an email." }, "language": { "type": "string", "description": "The language of the e-mail sent to the invitee. If none selected, the default end-users language will be used." }, "acceptUrl": { "type": "string", "format": "url", "description": "The url is shown only for \"Sent\" or \"Pending\" statuses." }, "options": { "type": "object", "properties": { "allowCorporateAccountBilling": { "type": "boolean", "default": false }, "limitCorporateAccountBillingToPartnerChargePoints": { "type": "boolean", "default": false, "description": "When corporate billing is enabled, creates or updates the assigned corporate billing policy to restrict corporate billing to the partner's charge points." }, "allowAccessToPrivateChargePoints": { "type": "boolean", "default": false }, "corporateBillingLimit": { "type": "number", "format": "decimal", "minimum": 0, "nullable": true, "description": "The individual corporate billing limit amount from the assigned corporate billing policy. Must be a positive decimal when set. When `null`, no individual limit is applied. Only applicable when `allowCorporateAccountBilling` is `true`." } } } }, "required": [ "partnerId" ], "description": "Partner Invite" } } } }, "responses": { "201": { "description": "Invite created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invites/v1.0/{partnerInvite}", "method": "GET", "operationId": "partnerInviteRead", "summary": "Partner Invite / Read", "description": "**This endpoint is deprecated. Use `resources/partner-invites/v2.0` instead.** Get a invite", "deprecated": true, "tags": [ "resource / partner invites" ], "parameters": { "path": { "partnerInvite": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invites/v1.0/{partnerInvite}", "method": "DELETE", "operationId": "partnerInviteDelete", "summary": "Partner Invite / Delete", "description": "**This endpoint is deprecated. Use `resources/partner-invites/v2.0` instead.** Delete an invite", "deprecated": true, "tags": [ "resource / partner invites" ], "parameters": { "path": { "partnerInvite": { "type": "integer", "required": true } } }, "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invites/v1.0/{partnerInvite}", "method": "PATCH", "operationId": "partnerInviteUpdate", "summary": "Partner Invite / Update", "description": "**This endpoint is deprecated. Use `resources/partner-invites/v2.0` instead.** Update a invite", "deprecated": true, "tags": [ "resource / partner invites" ], "parameters": { "path": { "partnerInvite": { "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partnerId": { "type": "integer" }, "sendViaEmail": { "type": "boolean" }, "email": { "type": "string", "format": "email", "description": "Email used to identify and associate the invitee." }, "language": { "type": "string", "description": "The language of the e-mail sent to the invitee. If none selected, the default end-users language will be used." }, "acceptUrl": { "type": "string", "format": "url", "description": "The url is shown only for \"Sent\" or \"Pending\" statuses." }, "options": { "type": "object", "properties": { "allowCorporateAccountBilling": { "type": "boolean", "default": false }, "limitCorporateAccountBillingToPartnerChargePoints": { "type": "boolean", "default": false, "description": "When corporate billing is enabled, updates the assigned corporate billing policy to restrict corporate billing to the partner's charge points. Omit the field to leave the current policy value unchanged." }, "allowAccessToPrivateChargePoints": { "type": "boolean", "default": false }, "corporateBillingLimit": { "type": "number", "format": "decimal", "minimum": 0, "nullable": true, "description": "The individual corporate billing limit amount from the assigned corporate billing policy. Must be a positive decimal when set. When `null`, no individual limit is applied. Only applicable when `allowCorporateAccountBilling` is `true`." } } } }, "description": "Partner Invite" } } } }, "responses": { "200": { "description": "Invite updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invites/v2.0", "method": "GET", "operationId": "partnerInvitesListingV2_0", "summary": "Partner invites / Listing", "description": "Get all partner invites. **Experimental endpoint — not yet a stable contract.** `partner-invites/v2.0` ships as **experimental / beta**. While experimental, its schema and behaviour may change **without a version bump — including breaking changes within `v2.0` itself**. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed.", "tags": [ "resource / partner invites" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "partnerId": { "type": "integer", "description": "Only list partner invites associated with a certain partner." }, "corporateBillingPolicyId": { "type": "integer", "description": "Only list partner invites associated with a certain corporate billing policy." }, "status": { "type": "string", "enum": [ "pending", "sent", "accepted" ], "description": "Partner invite status. - `pending` — The invite was created without sending an email and has not been accepted. - `sent` — The invite email was sent and has not been accepted. - `accepted` — The invite was accepted by a user." } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invites/v2.0", "method": "POST", "operationId": "partnerInviteCreateV2_0", "summary": "Partner invite / Create", "description": "Create a partner invite. Reimbursement coverage of specific RFIDs and vehicles (`allow`) can be declared here only when the invited email address resolves to an existing user of the partner's operator — the listed RFIDs and vehicles must belong to that user. When no such user exists yet, coverage of specific entities is rejected with a validation error; create the invite without it and declare the covered set via the update endpoint once the invite is accepted. **Experimental endpoint — not yet a stable contract.** `partner-invites/v2.0` ships as **experimental / beta**. While experimental, its schema and behaviour may change **without a version bump — including breaking changes within `v2.0` itself**. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed.", "tags": [ "resource / partner invites" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partnerId": { "type": "integer" }, "sendViaEmail": { "type": "boolean", "default": true }, "email": { "type": "string", "format": "email", "description": "Required if `sendViaEmail` is true or omitted. Optional when `sendViaEmail` is false; when provided, the invite is linked to the matching user without dispatching an email." }, "language": { "type": "string", "enum": [ "en", "bg", "mk", "el", "zh-CN", "zh-HK", "zh-TW", "pt", "sl", "hr", "it", "de", "hu", "fi", "is", "sv-SE", "da-DK", "nb-NO", "tr-TR", "es-ES", "ar", "ary", "he", "ta", "ms", "cy", "sr", "fr", "fr-MA", "ro", "lt", "uk", "ru", "nl", "ca-ES", "id", "ar-EG", "pl", "lo", "th", "sq-XK", "ga-IE", "bs", "ja", "ko-KR", "cs", "lv", "et", "az", "ka", "af", "hi", "de-CH", "fr-CH", "it-CH", "en-GB" ], "description": "IETF language tag." }, "accessPolicyId": { "type": "integer", "description": "The access policy ID to assign. Must reference a policy accessible to the partner. Omit the field when no policy should be assigned." }, "corporateBillingPolicyId": { "type": "integer", "description": "The corporate billing policy ID to assign. Must reference an active policy that belongs to the partner." }, "reimbursement": { "type": "object", "properties": { "policyId": { "type": "integer", "description": "The home-charging reimbursement policy attached to the invite. Must reference an active policy that belongs to the partner or has no partner. Omitted from the response when no policy is attached. When the policy resolves the electricity rate from the charge point, it is applied only to the invited user's charge points that have an electricity rate assigned. Charge points without one are skipped and the request still succeeds; assign an electricity rate to those charge points and re-apply the policy to cover them." }, "restrictions": { "type": "object", "properties": { "rfids": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow" ], "description": "Discriminator for a reimbursement coverage sub-restriction: - **none**: All of the invite's attached entities of this kind are covered. - **allow**: Only the explicitly listed entities are covered." }, "rfidIds": { "type": "array", "items": { "type": "integer" }, "description": "The covered set of RFID IDs. Required and must be non-empty when type is `allow`; each must belong to the invited user. Listed RFIDs that are not yet attached are attached automatically, and attached RFIDs left off the list are detached. Omitted when type is `none`." } }, "required": [ "type" ], "description": "Reimbursement coverage for the invite's RFIDs." }, "vehicles": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow" ], "description": "Discriminator for a reimbursement coverage sub-restriction: - **none**: All of the invite's attached entities of this kind are covered. - **allow**: Only the explicitly listed entities are covered." }, "vehicleIds": { "type": "array", "items": { "type": "integer" }, "description": "The covered set of vehicle IDs. Required and must be non-empty when type is `allow`; each must belong to the invited user. Listed vehicles that are not yet attached are attached automatically, and attached vehicles left off the list are detached. Omitted when type is `none`." } }, "required": [ "type" ], "description": "Reimbursement coverage for the invite's vehicles." } }, "description": "Which of the invite's RFIDs and vehicles are covered by reimbursement. On read this reports the current covered set. On write the submitted list declares the covered set: listed RFIDs/vehicles are attached automatically (they must belong to the invited user), and attached entities left off the list are detached." } }, "description": "Home-charging reimbursement settings for the invite. Ignored when home-charging reimbursement is disabled." } }, "required": [ "partnerId" ], "description": "Partner invite create payload." } } } }, "responses": { "201": { "description": "Created" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invites/v2.0/{partnerInvite}", "method": "GET", "operationId": "partnerInviteReadV2_0", "summary": "Partner invite / Read", "description": "Get a partner invite. **Experimental endpoint — not yet a stable contract.** `partner-invites/v2.0` ships as **experimental / beta**. While experimental, its schema and behaviour may change **without a version bump — including breaking changes within `v2.0` itself**. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed.", "tags": [ "resource / partner invites" ], "parameters": { "path": { "partnerInvite": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invites/v2.0/{partnerInvite}", "method": "DELETE", "operationId": "partnerInviteDeleteV2_0", "summary": "Partner invite / Delete", "description": "Delete a partner invite. **Experimental endpoint — not yet a stable contract.** `partner-invites/v2.0` ships as **experimental / beta**. While experimental, its schema and behaviour may change **without a version bump — including breaking changes within `v2.0` itself**. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed.", "tags": [ "resource / partner invites" ], "parameters": { "path": { "partnerInvite": { "type": "integer", "required": true } } }, "responses": { "204": { "description": "No content" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invites/v2.0/{partnerInvite}", "method": "PATCH", "operationId": "partnerInviteUpdateV2_0", "summary": "Partner invite / Update", "description": "Update a partner invite. **Experimental endpoint — not yet a stable contract.** `partner-invites/v2.0` ships as **experimental / beta**. While experimental, its schema and behaviour may change **without a version bump — including breaking changes within `v2.0` itself**. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed.", "tags": [ "resource / partner invites" ], "parameters": { "path": { "partnerInvite": { "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partnerId": { "type": "integer" }, "accessPolicyId": { "type": "integer", "nullable": true, "description": "The access policy ID to assign. Must reference a policy accessible to the partner. Send `null` to clear any assigned policy; omit the field to leave the current value unchanged." }, "corporateBillingPolicyId": { "type": "integer", "nullable": true, "description": "The corporate billing policy ID to assign. Must reference an active policy that belongs to the partner. Send `null` to clear any assigned policy; omit the field to leave the current value unchanged." }, "reimbursement": { "type": "object", "properties": { "policyId": { "type": "integer", "nullable": true, "description": "The home-charging reimbursement policy ID to attach. Must reference an active policy that belongs to the partner or has no partner. Send `null` to detach any policy; omit the field to leave the current value unchanged. When the policy resolves the electricity rate from the charge point, it is applied only to the invited user's charge points that have an electricity rate assigned. Charge points without one are skipped and the request still succeeds; assign an electricity rate to those charge points and re-apply the policy to cover them." }, "restrictions": { "type": "object", "properties": { "rfids": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow" ], "description": "Discriminator for a reimbursement coverage sub-restriction: - **none**: All of the invite's attached entities of this kind are covered. - **allow**: Only the explicitly listed entities are covered." }, "rfidIds": { "type": "array", "items": { "type": "integer" }, "description": "The covered set of RFID IDs. Required and must be non-empty when type is `allow`; each must belong to the invited user. Listed RFIDs that are not yet attached are attached automatically, and attached RFIDs left off the list are detached. Omitted when type is `none`." } }, "required": [ "type" ], "description": "Reimbursement coverage for the invite's RFIDs." }, "vehicles": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "allow" ], "description": "Discriminator for a reimbursement coverage sub-restriction: - **none**: All of the invite's attached entities of this kind are covered. - **allow**: Only the explicitly listed entities are covered." }, "vehicleIds": { "type": "array", "items": { "type": "integer" }, "description": "The covered set of vehicle IDs. Required and must be non-empty when type is `allow`; each must belong to the invited user. Listed vehicles that are not yet attached are attached automatically, and attached vehicles left off the list are detached. Omitted when type is `none`." } }, "required": [ "type" ], "description": "Reimbursement coverage for the invite's vehicles." } }, "description": "Which of the invite's RFIDs and vehicles are covered by reimbursement. On read this reports the current covered set. On write the submitted list declares the covered set: listed RFIDs/vehicles are attached automatically (they must belong to the invited user), and attached entities left off the list are detached." } }, "description": "Home-charging reimbursement settings for the invite. Omit the object to leave every reimbursement setting unchanged. Ignored when home-charging reimbursement is disabled." } }, "description": "Partner invite update payload." } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invoices/v1.0", "method": "GET", "operationId": "partnerInvoicesListing", "summary": "Partner Invoices / Listing", "description": "Get all Partner Invoices visible to the authenticated admin.", "tags": [ "resource / partner invoices" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "partnerId": { "type": "integer", "description": "Filter by partner ID." }, "settlementReportId": { "type": "integer", "description": "Filter by the source settlement report ID." }, "referenceId": { "type": "integer", "description": "Filter by the ID of the original partner invoice that a credit note cancels. Use this to find the credit note issued against a given invoice; combine with `type` to disambiguate. Matches nothing for regular invoices, which have no reference." }, "paymentStatus": { "type": "string", "enum": [ "unpaid", "partially_paid", "paid" ], "example": "unpaid", "description": "Partner invoice payment status: - **unpaid**: No payment has been recorded against the invoice. - **partially_paid**: A payment has been recorded but the full amount is not yet covered. - **paid**: The full amount has been paid." }, "type": { "type": "string", "enum": [ "invoice", "credit_note" ], "example": "invoice", "description": "Partner invoice document type: - **invoice**: A regular partner invoice generated from a settlement report. - **credit_note**: A credit note that cancels an original partner invoice. Always references the cancelled invoice via `referenceId`." }, "issuedFrom": { "type": "string", "format": "date", "description": "Include partner invoices whose issued date is on or after the given date (inclusive)." }, "issuedTo": { "type": "string", "format": "date", "description": "Include partner invoices whose issued date is on or before the given date (inclusive)." }, "dueFrom": { "type": "string", "format": "date", "description": "Include partner invoices whose due date is on or after the given date (inclusive)." }, "dueTo": { "type": "string", "format": "date", "description": "Include partner invoices whose due date is on or before the given date (inclusive)." }, "periodFrom": { "type": "string", "format": "date", "description": "Include partner invoices whose billing period starts on or after the given date (inclusive)." }, "periodTo": { "type": "string", "format": "date", "description": "Include partner invoices whose billing period ends on or before the given date (inclusive)." }, "externalId": { "type": "string", "maxLength": 255, "description": "An optional external identifier for integration purposes" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-invoices/v1.0/{partnerInvoice}", "method": "GET", "operationId": "partnerInvoiceRead", "summary": "Partner Invoice / Read", "description": "Get a single Partner Invoice including line items and seller/buyer details.", "tags": [ "resource / partner invoices" ], "parameters": { "path": { "partnerInvoice": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-revenues/v1.0", "method": "GET", "operationId": "revenuesListingDeprecated", "summary": "Revenues / Listing", "description": "Get all revenues", "deprecated": true, "tags": [ "resource / revenues & expenses" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "partnerId": { "type": "string", "format": "integer", "description": "Only list revenue associated with a certain partner" }, "dateFrom": { "type": "string", "format": "date-time", "description": "Date from based on created at" }, "dateTo": { "type": "string", "format": "date-time", "description": "Date to based on created at" }, "origin": { "type": "string", "enum": [ "electricity-tax-reimbursement", "session-cpo" ], "description": "Only list revenue by origin" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR", "description": "3-letter currency code (ISO 4217). Only list revenue by currency" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/partner-revenues/v1.1", "method": "GET", "operationId": "revenuesListing", "summary": "Revenues / Listing", "description": "This endpoint is deprecated. Use v1.2 for tax-inclusive amount breakdowns. Get all revenues", "deprecated": true, "tags": [ "resource / revenues & expenses" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "partnerId": { "type": "string", "format": "integer", "description": "Only list revenue associated with a certain partner" }, "settlementReportId": { "type": "string", "format": "integer", "description": "Only list revenue associated with a certain settlement report" }, "dateBefore": { "type": "string", "format": "date-time" }, "dateAfter": { "type": "string", "format": "date-time" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the revenue records that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the revenue records that were last updated on and before this datetime" }, "origin": { "type": "string", "enum": [ "electricity-tax-reimbursement", "private-evse-access-fee", "session-cpo" ], "description": "Only list revenue by origin" }, "currencyCode": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR", "description": "3-letter currency code (ISO 4217). Only list revenue by currency" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/partner-revenues/v1.2", "method": "GET", "operationId": "revenuesV1_2Listing", "summary": "Revenues / Listing", "description": "Get all revenues", "tags": [ "resource / revenues & expenses" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "partnerId": { "type": "string", "format": "integer", "description": "Only list revenue associated with a certain partner" }, "settlementReportId": { "type": "string", "format": "integer", "description": "Only list revenue associated with a certain settlement report" }, "origin": { "type": "string", "enum": [ "electricity-tax-reimbursement", "private-evse-access-fee", "session-cpo" ], "description": "Only list revenue by origin" }, "currencyCode": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR", "description": "3-letter currency code (ISO 4217). Only list revenue by currency" }, "dateBefore": { "type": "string", "format": "date-time" }, "dateAfter": { "type": "string", "format": "date-time" }, "chargePointId": { "type": "string", "format": "integer", "description": "Only list revenue associated with a certain charge point" }, "locationId": { "type": "string", "format": "integer", "description": "Only list revenue associated with a certain location" }, "partnerContractId": { "type": "string", "format": "integer", "description": "Only list revenue associated with a certain partner contract" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the revenue records that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the revenue records that were last updated on and before this datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/partner-settlement-reports/v1.0", "method": "GET", "operationId": "partnerSettlementReportsListing", "summary": "Partner Settlement Reports / Listing", "description": "Get all Partner Settlement Reports", "tags": [ "resource / partner settlement reports" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "partnerId": { "type": "integer" }, "periodAfter": { "type": "string", "format": "date" }, "periodBefore": { "type": "string", "format": "date" }, "customFields": { "type": "string", "example": "filter[customFields.invoiceReference]=INV-42", "description": "Filter a custom-field host resource by custom fields defined for that resource. Add one literal `customFields.` key to the existing `filter` object for each criterion. The identifier suffix is administrator-defined and is never enumerated in this schema or generated per tenant. Use a scalar for boolean, text, email, and URL fields. Boolean accepts booleans and integer `1` or `0`, as well as the strings `\"true\"`, `\"false\"`, `\"1\"`, and `\"0\"`. Text, email, and URL accept strings and use contains matching that is case- and accent-insensitive; backslashes, `%`, and `_` are treated literally rather than as pattern syntax. Use `from`, `to`, or both below the dotted key for number, date, and date-time fields. Both bounds are inclusive. Number bounds are decimal strings from `-99999999999999.999999` through `99999999999999.999999` with at most six decimal places; comparisons preserve submitted and stored decimal precision without rounding. Date bounds use `YYYY-MM-DD` and compare calendar dates without time-zone conversion. Date-time bounds use ISO 8601; offsets are normalized to UTC, and an omitted offset is interpreted as UTC. Multiple identifiers combine with AND. Empty scalar criteria and ranges whose bounds are empty are ignored. An identifier resolves only to its current active definition, so values belonging to a deleted definition never match if its identifier is reused. Operator-scoped filters match only host records whose current operator owner is assigned to the field; retained inapplicable values are excluded before pagination. Unknown, inaccessible, tenant-disabled, resource-disabled, deleted, and otherwise unavailable identifiers all return the same non-disclosing `404` response. An active accessible custom field whose filtering is disabled returns `422` with `Custom field \"{identifier}\" is not filterable for resource \"{resource}\".` Malformed objects or values, a criterion shape that is invalid for the field type, and a range whose `from` bound is greater than its `to` bound return `422`. Custom-field filters apply only to resource listings. They do not participate in search and do not depend on an `include` parameter; any unrelated includes are defined by the host resource. Examples: `filter[customFields.invoiceReference]=INV-42` and `filter[customFields.capacity][from]=10&filter[customFields.capacity][to]=20`. URL-encode the query keys and values when sending the request." }, "externalId": { "type": "string" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-settlement-reports/v1.0/{partnerSettlementReport}", "method": "GET", "operationId": "partnerSettlementReportRead", "summary": "Partner Settlement Report / Read", "description": "Get a single Partner Settlement Report", "tags": [ "resource / partner settlement reports" ], "parameters": { "path": { "partnerSettlementReport": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-settlement-reports/v1.0/{partnerSettlementReport}/records", "method": "GET", "operationId": "partnerSettlementReportPartnerSettlementRecordsListing", "summary": "Partner Settlement Report / Partner Settlement Records / Listing", "description": "Get all Partner Settlement Records", "tags": [ "resource / partner settlement reports" ], "parameters": { "path": { "partnerSettlementReport": { "type": "integer", "required": true } }, "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-settlement-reports/v1.0/{partnerSettlementReport}/records", "method": "POST", "operationId": "partnerSettlementReportPartnerSettlementRecordCreate", "summary": "Partner Settlement Report / Partner Settlement Record / Create", "description": "Create Partner Settlement Record", "tags": [ "resource / partner settlement reports" ], "parameters": { "path": { "partnerSettlementReport": { "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "paidAmount": { "type": "number" }, "note": { "type": "string" } }, "required": [ "date", "paidAmount", "note" ] } } } }, "responses": { "201": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-settlement-reports/v1.0/{partnerSettlementReport}/records/{PartnerSettlementRecord}", "method": "GET", "operationId": "partnertSettlementReportPartnerSettlementRecordRead", "summary": "Partner Settlement Report / Partner Settlement Record / Read", "description": "Read Partner Settlement Record", "tags": [ "resource / partner settlement reports" ], "parameters": { "path": { "partnerSettlementReport": { "type": "integer", "required": true }, "PartnerSettlementRecord": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-settlement-reports/v1.0/{partnerSettlementReport}/records/{PartnerSettlementRecord}", "method": "PUT", "operationId": "partnerSettlementReportPartnerSettlementRecordUpdate", "summary": "Partner Settlement Report / Partner Settlement Record / Update", "description": "Update a single Partner Settlement Record", "tags": [ "resource / partner settlement reports" ], "parameters": { "path": { "partnerSettlementReport": { "type": "integer", "required": true }, "PartnerSettlementRecord": { "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "paidAmount": { "type": "number" }, "note": { "type": "string" } }, "required": [ "date", "paidAmount", "note" ] } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partner-settlement-reports/v1.0/{partnerSettlementReport}/records/{PartnerSettlementRecord}", "method": "DELETE", "operationId": "partnerSettlementReportPartnerSettlementRecordDelete", "summary": "Partner Settlement Report / Partner Settlement Record / Delete", "description": "Delete a single Partner Settlement Record", "tags": [ "resource / partner settlement reports" ], "parameters": { "path": { "partnerSettlementReport": { "type": "integer", "required": true }, "PartnerSettlementRecord": { "type": "integer", "required": true } } }, "responses": { "204": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v1.0", "method": "GET", "operationId": "partnersListingDeprecated", "summary": "Partners / Listing", "description": "Get all partners", "deprecated": true, "tags": [ "resource / partners" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "description": "Lists partners from the specified country" }, "search": { "type": "string", "description": "Case-insensitive partial match against partner name and business name. Values shorter than 3 characters are ignored." }, "regNo": { "type": "string", "description": "Lists partners with the specified regNo" }, "tag": { "type": "string", "description": "Only list partners that have the specified tag assigned." }, "hasRoamingOperator": { "type": "boolean", "description": "When true, lists only partners linked to at least one roaming operator (roaming partners). When false, lists only partners with no roaming operator link (business partners)." }, "roamingOperatorId": { "type": "integer", "description": "Lists only partners linked to the specified roaming operator. IDs correspond to the roaming operators exposed by the roaming operators / roaming CPOs endpoints." }, "externalId": { "type": "string", "nullable": true, "description": "Only list partner, identified by the externalId" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partners that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partners that were last updated on and before this datetime" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partner records that were created on and after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partner records that were created on and before this datetime" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v1.0", "method": "POST", "operationId": "partnerCreateDeprecated", "summary": "Partner / Create", "description": "Create new partner", "deprecated": true, "tags": [ "resource / partners" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Company name of the Partner. The value is written to the English (`en`) locale only. To write this field in other locales, use `translatedName` in Partners v2.0." }, "regNo": { "type": "string", "nullable": true }, "vatNo": { "type": "string", "nullable": true }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW", null ], "nullable": true }, "city": { "type": "string", "nullable": true, "description": "City of the Partner. The value is written to the English (`en`) locale only. To write this field in other locales, use `translatedCity` in Partners v2.0." }, "postcode": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true, "description": "Address of the Partner. The value is written to the English (`en`) locale only. To write this field in other locales, use `translatedAddress` in Partners v2.0." }, "contactPerson": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "faultNotificationsEmail": { "type": "string", "format": "email", "nullable": true }, "monthlyPlatformFee": { "type": "number", "format": "decimal", "nullable": true }, "options": { "type": "object", "properties": { "createUsers": { "type": "boolean", "default": false }, "addUserBalance": { "type": "boolean", "default": false }, "supplierOnReceipts": { "type": "boolean", "default": false }, "allowToControlTariffs": { "type": "boolean", "default": false, "description": "Allows the Partner to update the tariff pricing." }, "allowToControlTariffGroups": { "type": "boolean", "default": false, "description": "In addition to `allowToControlTariffs`, the Partner would also be able to manage Tariff Groups - attach and remove Tariffs, change Tariffs order in the Tariff Group." } } }, "corporateBilling": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "monthlyLimit": { "type": "number", "format": "decimal", "nullable": true }, "discount": { "type": "number", "format": "decimal", "nullable": true } } }, "externalId": { "type": "string", "nullable": true, "description": "Third party identifier of the partner" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Partner created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v1.0/{partner}", "method": "GET", "operationId": "partnerReadDeprecated", "summary": "Partner / Read", "description": "Get a partner", "deprecated": true, "tags": [ "resource / partners" ], "parameters": { "path": { "partner": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v1.0/{partner}", "method": "DELETE", "operationId": "partnerDeleteDeprecated", "summary": "Partner / Delete", "description": "Delete a partner", "deprecated": true, "tags": [ "resource / partners" ], "parameters": { "path": { "partner": { "type": "integer", "required": true } } }, "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v1.0/{partner}", "method": "PATCH", "operationId": "partnerUpdateDeprecated", "summary": "Partner / Update", "description": "Update a partner", "deprecated": true, "tags": [ "resource / partners" ], "parameters": { "path": { "partner": { "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Company name of the Partner. The value is written to the English (`en`) locale only. To write this field in other locales, use `translatedName` in Partners v2.0." }, "regNo": { "type": "string", "nullable": true }, "vatNo": { "type": "string", "nullable": true }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW", null ], "nullable": true }, "city": { "type": "string", "nullable": true, "description": "City of the Partner. The value is written to the English (`en`) locale only. To write this field in other locales, use `translatedCity` in Partners v2.0." }, "postcode": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true, "description": "Address of the Partner. The value is written to the English (`en`) locale only. To write this field in other locales, use `translatedAddress` in Partners v2.0." }, "contactPerson": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "faultNotificationsEmail": { "type": "string", "format": "email", "nullable": true }, "monthlyPlatformFee": { "type": "number", "format": "decimal", "nullable": true }, "options": { "type": "object", "properties": { "createUsers": { "type": "boolean", "default": false }, "addUserBalance": { "type": "boolean", "default": false }, "supplierOnReceipts": { "type": "boolean", "default": false }, "allowToControlTariffs": { "type": "boolean", "default": false, "description": "Allows the Partner to update the tariff pricing." }, "allowToControlTariffGroups": { "type": "boolean", "default": false, "description": "In addition to `allowToControlTariffs`, the Partner would also be able to manage Tariff Groups - attach and remove Tariffs, change Tariffs order in the Tariff Group." } } }, "corporateBilling": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "monthlyLimit": { "type": "number", "format": "decimal", "nullable": true }, "discount": { "type": "number", "format": "decimal", "nullable": true } } }, "externalId": { "type": "string", "nullable": true, "description": "Third party identifier of the partner" } }, "required": [ "name" ] } ] } } } }, "responses": { "200": { "description": "Partner updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0", "method": "GET", "operationId": "partnersListing", "summary": "Partners / Listing", "description": "Get all partners", "tags": [ "resource / partners" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "description": "Lists partners from the specified country" }, "search": { "type": "string", "description": "Case-insensitive partial match against partner name and business name. Values shorter than 3 characters are ignored." }, "regNo": { "type": "string", "description": "Lists partners with the specified regNo" }, "tag": { "type": "string", "description": "Only list partners that have the specified tag assigned." }, "hasRoamingOperator": { "type": "boolean", "description": "When true, lists only partners linked to at least one roaming operator (roaming partners). When false, lists only partners with no roaming operator link (business partners)." }, "roamingOperatorId": { "type": "integer", "description": "Lists only partners linked to the specified roaming operator. IDs correspond to the roaming operators exposed by the roaming operators / roaming CPOs endpoints." }, "externalId": { "type": "string", "nullable": true, "description": "Only list partner, identified by the externalId" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partners that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partners that were last updated on and before this datetime" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partner records that were created on and after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the partner records that were created on and before this datetime" } } } }, "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "notes" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0", "method": "POST", "operationId": "partnerCreate", "summary": "Partner / Create", "description": "Create new partner", "tags": [ "resource / partners" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "businessName": { "type": "string", "description": "The Partner's business name is used when showing the name of the Partner to EV drivers and admin users. If not provided, the `name` will be used instead." }, "reimbursement": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether home-charging reimbursement is enabled for the Partner. Disabling it stops future reimbursement for the Partner. The reimbursement policies that are currently active for it remain attached but become ineligible, and the invites attached to them stop producing reimbursement records. Reimbursement records and reports that already exist are not affected." }, "payoutMode": { "type": "string", "enum": [ "operator_managed", "partner_managed" ], "description": "Determines who pays out the home-charging reimbursement to the drivers: - **operator_managed**: The operator handles the payouts on behalf of the Partner. - **partner_managed**: The Partner handles the payouts to their own drivers." }, "cycle": { "type": "string", "enum": [ "monthly", "quarterly", "annual" ], "description": "How often the home-charging reimbursement is calculated and reported: - **monthly**: Reimbursement is processed every month. - **quarterly**: Reimbursement is processed every three months. - **annual**: Reimbursement is processed every year." } }, "description": "Home-charging reimbursement settings of the Partner. Submitting this object while the home-charging reimbursement feature is disabled for the operator is rejected with a `422` response." }, "notifications": { "type": "object", "properties": { "technical": { "type": "object", "properties": { "chargePointFaults": { "type": "boolean", "default": false } } }, "billing": { "type": "object", "properties": { "settlementReports": { "type": "boolean", "default": false } } } } }, "id": { "type": "integer" }, "name": { "type": "string", "description": "**This property is deprecated. Use `translatedName` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedName`. Company name of the Partner" }, "translatedName": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "Company name of the Partner per locale. Whenever this field is submitted — on both create and update — the array must contain an `en` entry. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the name: locales absent from the array are cleared. Omit the field to leave every existing locale untouched. An empty array is rejected on both create and update — the name cannot be cleared. Cannot be provided together with the deprecated `name`." }, "regNo": { "type": "string", "nullable": true }, "vatNo": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `translatedAddress` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedAddress`." }, "translatedAddress": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "Address of the Partner per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the address: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `address`." }, "postcode": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `translatedCity` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedCity`." }, "translatedCity": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "City of the Partner per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the city: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `city`." }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "nullable": true }, "region": { "type": "string", "nullable": true, "description": "When country is not in US, AU, CA, UM or RO, you can provide the region" }, "translatedRegion": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "Region of the Partner per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the region: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Rejected when the Partner's country supports states (US, AU, CA, UM, RO) — `state` applies instead and is not translatable. Cannot be provided together with the deprecated `region`." }, "state": { "anyOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "When the country is US." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "When the country is AU." }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" ], "description": "When the country is CA." }, { "type": "string", "enum": [ "81", "84", "85", "67", "89", "71", "76", "95", "79" ], "description": "When the country is UM." }, { "type": "string", "enum": [ "AB", "AR", "AG", "BC", "BH", "BN", "BT", "BV", "BR", "B", "BZ", "CL", "CS", "CT", "CV", "DB", "DJ", "GL", "GR", "GJ", "HR", "HD", "IL", "IS", "IF", "MM", "MH", "MS", "NT", "OT", "PH", "SM", "SJ", "SB", "SV", "TR", "TM", "TL", "VS", "VL", "VN" ], "description": "When the country is RO." } ], "description": "When the selected country is one of US, AU, CA, UM or RO" }, "contactDetails": { "type": "object", "properties": { "administrative": { "type": "object", "properties": { "contactPerson": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "nullable": true }, "technical": { "type": "object", "properties": { "contactPerson": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "nullable": true }, "billing": { "type": "object", "properties": { "contactPerson": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "nullable": true } }, "nullable": true }, "monthlyPlatformFee": { "type": "number", "format": "decimal", "nullable": true }, "receiptsPrefix": { "type": "string", "nullable": true, "description": "Prefix used for the Partner's receipt numbering. Takes effect only when `options.supplierOnReceipts` is `true`." }, "receiptsStartingNumber": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "nullable": true, "description": "Starting number for the Partner's receipt numbering. Numeric string; leading zeros are preserved. Takes effect only when `options.supplierOnReceipts` is `true`." }, "invoiceNumberPrefix": { "type": "string", "minLength": 1, "maxLength": 10, "nullable": true, "description": "Prefix used for the Partner's invoice numbering. Must be globally unique across all partner invoice prefixes, invoice integration prefixes, and previously-issued invoice prefixes. Takes effect only when `options.supplierOnInvoices` is `true`." }, "startingInvoiceNumber": { "type": "string", "pattern": "^\\d+$", "nullable": true, "description": "Starting number for the Partner's invoice numbering. Non-negative numeric string; leading zeros are preserved. Takes effect only when `options.supplierOnInvoices` is `true`." }, "options": { "type": "object", "properties": { "userVisibility": { "type": "string", "enum": [ "none", "all", "corporateBillingOnly" ], "default": "none", "description": "Controls which invited users are visible to Partner admins: - `none`: Partner admins cannot see any invited users - `all`: Partner admins can see all users who accepted their invite - `corporateBillingOnly`: Partner admins can see only users whose invite has corporate billing enabled" }, "allowViewingUsersWhoAcceptedInvite": { "type": "boolean", "default": false, "description": "**Deprecated.** Use `userVisibility` instead. When enabled (`true`), maps to `userVisibility: all`. When disabled (`false`), maps to `userVisibility: none`. If both `userVisibility` and `allowViewingUsersWhoAcceptedInvite` are provided, `userVisibility` takes precedence." }, "createUsers": { "type": "boolean", "default": false }, "addUserBalance": { "type": "boolean", "default": false, "description": "When set to false the API tokens related to this partner would not receive the users' balance in the response." }, "allowViewingAllSessionsOfInvitedUsers": { "type": "boolean", "default": true, "description": "If true, partner admins can view all sessions of users who accepted their invites. If false, partner admins can only view sessions that occurred on their charge points or were paid with their corporate billing." }, "supplierOnReceipts": { "type": "boolean", "default": false }, "supplierOnInvoices": { "type": "boolean", "default": false, "description": "When enabled, the Partner's data is used on invoices issued for sessions linked to this Partner." }, "allowToControlTariffs": { "type": "boolean", "default": false, "description": "Allows the Partner to update the tariff pricing." }, "allowToControlTariffGroups": { "type": "boolean", "default": false, "description": "In addition to `allowToControlTariffs`, the Partner would also be able to manage Tariff Groups - attach and remove Tariffs, change Tariffs order in the Tariff Group." }, "allowToControlCpConfigurations": { "type": "boolean", "default": false, "description": "Allows the Partner to control configurations on their charge points." }, "allowToLogExemptPeriods": { "type": "boolean", "default": false, "description": "Allows Partner admins with the Maintain permission from the DowntimePeriods permission set to log exempt periods." }, "settlementReportBreakdown": { "type": "string", "enum": [ "none", "by_location", "by_partner_contract", "by_location_and_partner_contract" ], "default": "none", "description": "Controls how settlement report line items are aggregated for the Partner: - `none`: No breakdown, single aggregated report. - `by_location`: Separate breakdown per location. - `by_partner_contract`: Separate breakdown per partner contract. - `by_location_and_partner_contract`: Breakdown by both location and partner contract." } } }, "corporateBilling": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "monthlyLimit": { "type": "number", "format": "decimal", "nullable": true, "description": "**Deprecated.** Use `limit` with `frequency` instead. When this field is provided, it is equivalent to setting `frequency` to 'monthly' and `limit` to the provided value. Note: Cannot be provided together with `limit`." }, "frequency": { "type": "string", "enum": [ "monthly", "quarterly", "semiAnnually", "annually" ], "description": "The billing frequency for the limit. Required when `limit` is first set. On subsequent updates, can be changed independently." }, "limit": { "type": "number", "format": "decimal", "minimum": 0, "nullable": true, "description": "The billing limit for the specified frequency. Requires `frequency` to be set when first created. On subsequent updates, can be changed independently." }, "discount": { "type": "number", "format": "decimal", "nullable": true } } }, "externalId": { "type": "string", "nullable": true, "description": "Third party identifier of the partner" }, "bankDetails": { "type": "object", "properties": { "bankIban": { "type": "string", "nullable": true, "description": "IBAN of the bank account." }, "bankCode": { "type": "string", "nullable": true, "description": "Bank code assigned by a central bank, a bank supervisory body or a Bankers Association in the country." }, "bankAccountNumber": { "type": "string", "nullable": true, "description": "Bank account number." }, "bankAccountType": { "type": "string", "nullable": true, "description": "Type of the bank account." }, "bankBic": { "type": "string", "nullable": true, "description": "BIC/SWIFT code of the bank." }, "bankName": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `translatedBankName` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedBankName`. Ignored when the bank name field is disabled in the operator's bank details settings. Name of the bank." }, "bankAddress": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `translatedBankAddress` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedBankAddress`. Ignored when the bank address field is disabled in the operator's bank details settings. Address of the bank." }, "bankAccountHolder": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `translatedBankAccountHolder` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedBankAccountHolder`. Ignored when the bank account holder field is disabled in the operator's bank details settings. Name of the bank account holder." }, "translatedBankName": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "Name of the bank per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the bank name: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `bankName`. Ignored when the bank name field is disabled in the operator's bank details settings." }, "translatedBankAddress": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "Address of the bank per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the bank address: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `bankAddress`. Ignored when the bank address field is disabled in the operator's bank details settings." }, "translatedBankAccountHolder": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "Name of the bank account holder per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the bank account holder: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `bankAccountHolder`. Ignored when the bank account holder field is disabled in the operator's bank details settings." } } }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" }, "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." } }, "description": "At least one of `name` or `translatedName` must be provided. Supplying both is rejected with a `422` response. When `translatedName` is used it must carry an `en` entry." } } } }, "responses": { "201": { "description": "Partner created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0/{partner}", "method": "GET", "operationId": "partnerRead", "summary": "Partner / Read", "description": "Get a partner", "tags": [ "resource / partners" ], "parameters": { "path": { "partner": { "type": "integer", "required": true } }, "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "notes" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0/{partner}", "method": "DELETE", "operationId": "partnerDelete", "summary": "Partner / Delete", "description": "Delete a partner", "tags": [ "resource / partners" ], "parameters": { "path": { "partner": { "type": "integer", "required": true } } }, "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0/{partner}", "method": "PATCH", "operationId": "partnerUpdate", "summary": "Partner / Update", "description": "Update a partner", "tags": [ "resource / partners" ], "parameters": { "path": { "partner": { "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "businessName": { "type": "string", "description": "The Partner's business name is used when showing the name of the Partner to EV drivers and admin users." }, "reimbursement": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether home-charging reimbursement is enabled for the Partner. Disabling it stops future reimbursement for the Partner. The reimbursement policies that are currently active for it remain attached but become ineligible, and the invites attached to them stop producing reimbursement records. Reimbursement records and reports that already exist are not affected." }, "payoutMode": { "type": "string", "enum": [ "operator_managed", "partner_managed" ], "description": "Determines who pays out the home-charging reimbursement to the drivers: - **operator_managed**: The operator handles the payouts on behalf of the Partner. - **partner_managed**: The Partner handles the payouts to their own drivers." }, "cycle": { "type": "string", "enum": [ "monthly", "quarterly", "annual" ], "nullable": true, "description": "How often the home-charging reimbursement is calculated and reported: - **monthly**: Reimbursement is processed every month. - **quarterly**: Reimbursement is processed every three months. - **annual**: Reimbursement is processed every year." } }, "description": "Home-charging reimbursement settings of the Partner. Submitting this object while the home-charging reimbursement feature is disabled for the operator is rejected with a `422` response." }, "notifications": { "type": "object", "properties": { "technical": { "type": "object", "properties": { "chargePointFaults": { "type": "boolean", "default": false } } }, "billing": { "type": "object", "properties": { "settlementReports": { "type": "boolean", "default": false } } } } }, "id": { "type": "integer" }, "name": { "type": "string", "description": "**This property is deprecated. Use `translatedName` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedName`. Company name of the Partner" }, "translatedName": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "Company name of the Partner per locale. Whenever this field is submitted — on both create and update — the array must contain an `en` entry. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the name: locales absent from the array are cleared. Omit the field to leave every existing locale untouched. An empty array is rejected on both create and update — the name cannot be cleared. Cannot be provided together with the deprecated `name`." }, "regNo": { "type": "string", "nullable": true }, "vatNo": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `translatedAddress` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedAddress`." }, "translatedAddress": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "Address of the Partner per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the address: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `address`." }, "postcode": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `translatedCity` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedCity`." }, "translatedCity": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "City of the Partner per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the city: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `city`." }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "nullable": true }, "region": { "type": "string", "nullable": true, "description": "When country is not in US, AU, CA, UM or RO, you can provide the region" }, "translatedRegion": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "Region of the Partner per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the region: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Rejected when the Partner's country supports states (US, AU, CA, UM, RO) — `state` applies instead and is not translatable. Cannot be provided together with the deprecated `region`." }, "state": { "anyOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "When the country is US." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "When the country is AU." }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" ], "description": "When the country is CA." }, { "type": "string", "enum": [ "81", "84", "85", "67", "89", "71", "76", "95", "79" ], "description": "When the country is UM." }, { "type": "string", "enum": [ "AB", "AR", "AG", "BC", "BH", "BN", "BT", "BV", "BR", "B", "BZ", "CL", "CS", "CT", "CV", "DB", "DJ", "GL", "GR", "GJ", "HR", "HD", "IL", "IS", "IF", "MM", "MH", "MS", "NT", "OT", "PH", "SM", "SJ", "SB", "SV", "TR", "TM", "TL", "VS", "VL", "VN" ], "description": "When the country is RO." } ], "description": "When the selected country is one of US, AU, CA, UM or RO" }, "contactDetails": { "type": "object", "properties": { "administrative": { "type": "object", "properties": { "contactPerson": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "nullable": true }, "technical": { "type": "object", "properties": { "contactPerson": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "nullable": true }, "billing": { "type": "object", "properties": { "contactPerson": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "nullable": true } }, "nullable": true }, "monthlyPlatformFee": { "type": "number", "format": "decimal", "nullable": true }, "receiptsPrefix": { "type": "string", "nullable": true, "description": "Prefix used for the Partner's receipt numbering. Takes effect only when `options.supplierOnReceipts` is `true`." }, "receiptsStartingNumber": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "nullable": true, "description": "Starting number for the Partner's receipt numbering. Numeric string; leading zeros are preserved. Takes effect only when `options.supplierOnReceipts` is `true`." }, "invoiceNumberPrefix": { "type": "string", "minLength": 1, "maxLength": 10, "nullable": true, "description": "Prefix used for the Partner's invoice numbering. Must be globally unique across all partner invoice prefixes, invoice integration prefixes, and previously-issued invoice prefixes. Takes effect only when `options.supplierOnInvoices` is `true`." }, "startingInvoiceNumber": { "type": "string", "pattern": "^\\d+$", "nullable": true, "description": "Starting number for the Partner's invoice numbering. Non-negative numeric string; leading zeros are preserved. Takes effect only when `options.supplierOnInvoices` is `true`." }, "options": { "type": "object", "properties": { "userVisibility": { "type": "string", "enum": [ "none", "all", "corporateBillingOnly" ], "default": "none", "description": "Controls which invited users are visible to Partner admins: - `none`: Partner admins cannot see any invited users - `all`: Partner admins can see all users who accepted their invite - `corporateBillingOnly`: Partner admins can see only users whose invite has corporate billing enabled" }, "allowViewingUsersWhoAcceptedInvite": { "type": "boolean", "default": false, "description": "**Deprecated.** Use `userVisibility` instead. When enabled (`true`), maps to `userVisibility: all`. When disabled (`false`), maps to `userVisibility: none`. If both `userVisibility` and `allowViewingUsersWhoAcceptedInvite` are provided, `userVisibility` takes precedence." }, "createUsers": { "type": "boolean", "default": false }, "addUserBalance": { "type": "boolean", "default": false, "description": "When set to false the API tokens related to this partner would not receive the users' balance in the response." }, "allowViewingAllSessionsOfInvitedUsers": { "type": "boolean", "default": true, "description": "If true, partner admins can view all sessions of users who accepted their invites. If false, partner admins can only view sessions that occurred on their charge points or were paid with their corporate billing." }, "supplierOnReceipts": { "type": "boolean", "default": false }, "supplierOnInvoices": { "type": "boolean", "default": false, "description": "When enabled, the Partner's data is used on invoices issued for sessions linked to this Partner." }, "allowToControlTariffs": { "type": "boolean", "default": false, "description": "Allows the Partner to update the tariff pricing." }, "allowToControlTariffGroups": { "type": "boolean", "default": false, "description": "In addition to `allowToControlTariffs`, the Partner would also be able to manage Tariff Groups - attach and remove Tariffs, change Tariffs order in the Tariff Group." }, "allowToControlCpConfigurations": { "type": "boolean", "default": false, "description": "Allows the Partner to control configurations on their charge points." }, "allowToLogExemptPeriods": { "type": "boolean", "default": false, "description": "Allows Partner admins with the Maintain permission from the DowntimePeriods permission set to log exempt periods." }, "settlementReportBreakdown": { "type": "string", "enum": [ "none", "by_location", "by_partner_contract", "by_location_and_partner_contract" ], "default": "none", "description": "Controls how settlement report line items are aggregated for the Partner: - `none`: No breakdown, single aggregated report. - `by_location`: Separate breakdown per location. - `by_partner_contract`: Separate breakdown per partner contract. - `by_location_and_partner_contract`: Breakdown by both location and partner contract." } } }, "corporateBilling": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "monthlyLimit": { "type": "number", "format": "decimal", "nullable": true, "description": "**Deprecated.** Use `limit` with `frequency` instead. When this field is provided, it is equivalent to setting `frequency` to 'monthly' and `limit` to the provided value. Note: Cannot be provided together with `limit`." }, "frequency": { "type": "string", "enum": [ "monthly", "quarterly", "semiAnnually", "annually" ], "description": "The billing frequency for the limit. Required when `limit` is first set. On subsequent updates, can be changed independently." }, "limit": { "type": "number", "format": "decimal", "minimum": 0, "nullable": true, "description": "The billing limit for the specified frequency. Requires `frequency` to be set when first created. On subsequent updates, can be changed independently." }, "discount": { "type": "number", "format": "decimal", "nullable": true } } }, "externalId": { "type": "string", "nullable": true, "description": "Third party identifier of the partner" }, "bankDetails": { "type": "object", "properties": { "bankIban": { "type": "string", "nullable": true, "description": "IBAN of the bank account." }, "bankCode": { "type": "string", "nullable": true, "description": "Bank code assigned by a central bank, a bank supervisory body or a Bankers Association in the country." }, "bankAccountNumber": { "type": "string", "nullable": true, "description": "Bank account number." }, "bankAccountType": { "type": "string", "nullable": true, "description": "Type of the bank account." }, "bankBic": { "type": "string", "nullable": true, "description": "BIC/SWIFT code of the bank." }, "bankName": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `translatedBankName` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedBankName`. Ignored when the bank name field is disabled in the operator's bank details settings. Name of the bank." }, "bankAddress": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `translatedBankAddress` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedBankAddress`. Ignored when the bank address field is disabled in the operator's bank details settings. Address of the bank." }, "bankAccountHolder": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `translatedBankAccountHolder` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedBankAccountHolder`. Ignored when the bank account holder field is disabled in the operator's bank details settings. Name of the bank account holder." }, "translatedBankName": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "Name of the bank per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the bank name: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `bankName`. Ignored when the bank name field is disabled in the operator's bank details settings." }, "translatedBankAddress": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "Address of the bank per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the bank address: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `bankAddress`. Ignored when the bank address field is disabled in the operator's bank details settings." }, "translatedBankAccountHolder": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string" } }, "required": [ "locale", "translation" ] }, "description": "Name of the bank account holder per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the bank account holder: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `bankAccountHolder`. Ignored when the bank account holder field is disabled in the operator's bank details settings." } } }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } } } ], "description": "Partner update data" } } } }, "responses": { "200": { "description": "Partner updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0/{partner}/admins", "method": "GET", "operationId": "partnerAdminsListing", "summary": "Partner / Admins / Listing", "description": "List all administrators for a specific partner. Only partner and partnerSiteManager admin types are returned. **Required permission:** `Admins.view`", "tags": [ "resource / partners" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "adminType": { "type": "string", "enum": [ "partner", "partnerSiteManager" ], "description": "Filter by administrator type: * `partner` - Full partner access administrators * `partnerSiteManager` - Location-restricted access administrators" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0/{partner}/admins", "method": "POST", "operationId": "partnerAdminCreate", "summary": "Partner / Admin / Create", "description": "Create a new administrator for a specific partner. The administrator type must be either `partner` or `partnerSiteManager`. For `partnerSiteManager`, locationIds is required and must contain valid location IDs owned by the partner. **Required permission:** `Admins.create`", "tags": [ "resource / partners" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Name of the administrator" }, "email": { "type": "string", "format": "email", "maxLength": 255, "description": "Email address of the administrator (must be unique across all admins)" }, "password": { "type": "string", "description": "Password with a minimum length of 6 characters. It must match passwordConfirmation." }, "passwordConfirmation": { "type": "string", "description": "Must match the password field" }, "adminType": { "type": "string", "enum": [ "partner", "partnerSiteManager" ], "description": "Type of partner administrator: * `partner` - Full partner access, uses roles from partner role group * `partnerSiteManager` - Location-restricted access, uses roles from partner site manager role group" }, "roleId": { "type": "integer", "description": "Role ID (must be valid for the selected adminType)" }, "locale": { "type": "string", "maxLength": 10, "example": "en", "nullable": true, "description": "Locale code for the administrator" }, "whitelistedIps": { "type": "array", "items": { "type": "string", "format": "ipv4" }, "example": [ "192.168.1.1" ], "description": "List of IP addresses allowed for UI access restriction" }, "locationIds": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ], "description": "Location IDs the administrator can manage. Required when adminType is `partnerSiteManager`." } }, "required": [ "name", "email", "password", "passwordConfirmation", "adminType", "roleId" ] } } } }, "responses": { "201": { "description": "Partner administrator created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0/{partner}/admins/{admin}", "method": "DELETE", "operationId": "partnerAdminDelete", "summary": "Partner / Admin / Delete", "description": "Delete a partner administrator. Cannot delete yourself (the authenticated admin making the request). **Required permission:** `Admins.delete`", "tags": [ "resource / partners" ], "responses": { "204": { "description": "Partner administrator deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0/{partner}/admins/{admin}", "method": "PATCH", "operationId": "partnerAdminUpdate", "summary": "Partner / Admin / Update", "description": "Update an existing partner administrator. All fields are optional. Only provided fields are updated. For `partnerSiteManager`, locationIds can be updated to change managed locations. **Required permission:** `Admins.update`", "tags": [ "resource / partners" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Name of the administrator" }, "email": { "type": "string", "format": "email", "maxLength": 255, "description": "Email address of the administrator (must remain unique)" }, "password": { "type": "string", "description": "New password with a minimum length of 6 characters. If provided, it must match passwordConfirmation." }, "passwordConfirmation": { "type": "string", "description": "Must match the password field when password is provided" }, "roleId": { "type": "integer", "description": "Role ID (must be valid for the admin's current type)" }, "locale": { "type": "string", "maxLength": 10, "example": "en", "nullable": true, "description": "Locale code for the administrator" }, "whitelistedIps": { "type": "array", "items": { "type": "string", "format": "ipv4" }, "example": [ "192.168.1.1" ], "description": "List of IP addresses for UI access restriction (replaces existing list)" }, "locationIds": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ], "description": "Location IDs the administrator can manage. Only applicable for `partnerSiteManager` type." } } } } } }, "responses": { "200": { "description": "Partner administrator updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0/{partner}/notes", "method": "GET", "operationId": "partnerNotesListing", "summary": "Partner / Notes / Listing", "description": "List all notes for a specific partner. Notes are returned with pinned notes first, then ordered by creation date descending. **Required permission:** `Notes.view`", "tags": [ "resource / partners" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "pinned": { "type": "boolean", "example": true, "description": "Filter by pinned status" }, "createdAfter": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z", "description": "Filter notes created on or after this ISO-8601 datetime" }, "createdBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes created on or before this ISO-8601 datetime" }, "updatedAfter": { "type": "string", "format": "date-time", "example": "2025-12-01T00:00:00Z", "description": "Filter notes updated on or after this ISO-8601 datetime (useful for delta sync)" }, "updatedBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes updated on or before this ISO-8601 datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0/{partner}/notes", "method": "POST", "operationId": "partnerNoteCreate", "summary": "Partner / Note / Create", "description": "Create a new note for a specific partner. **Required permission:** `Notes.create`", "tags": [ "resource / partners" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Important maintenance note", "description": "Short summary or title of the note (required)" }, "details": { "type": "string", "maxLength": 2000, "example": "This charge point requires monthly inspection due to high usage.", "description": "Detailed content of the note (optional)" }, "pinned": { "type": "boolean", "default": false, "example": false, "description": "Whether the note should be pinned (optional, defaults to false)" } }, "required": [ "summary" ] } } } }, "responses": { "201": { "description": "Note created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0/{partner}/notes/{note}", "method": "GET", "operationId": "partnerNoteShow", "summary": "Partner / Note / Read", "description": "Get a specific note for a partner. **Required permission:** `Notes.view`", "tags": [ "resource / partners" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0/{partner}/notes/{note}", "method": "DELETE", "operationId": "partnerNoteDelete", "summary": "Partner / Note / Delete", "description": "Delete a specific note from a partner. Notes are permanently deleted (hard delete). **Required permission:** `Notes.delete`", "tags": [ "resource / partners" ], "responses": { "204": { "description": "Note deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/partners/v2.0/{partner}/notes/{note}", "method": "PATCH", "operationId": "partnerNoteUpdate", "summary": "Partner / Note / Update", "description": "Update a specific note for a partner. **Required permissions:** - `Notes.update` for updating summary and details - `Notes.pin` for updating the pinned field (in addition to Notes.update if other fields are included)", "tags": [ "resource / partners" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Updated maintenance note", "description": "Short summary or title of the note" }, "details": { "type": "string", "maxLength": 2000, "example": "Updated inspection schedule.", "nullable": true, "description": "Detailed content of the note. Send null to clear." }, "pinned": { "type": "boolean", "example": true, "description": "Whether the note should be pinned. Requires Notes.pin permission." } } } } } }, "responses": { "200": { "description": "Note updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/payment-terminals/v1.0", "method": "GET", "operationId": "getPaymentTerminalsDeprecated", "summary": "Payment Terminals / Listing", "description": "**This endpoint is deprecated and will be removed on Tue, 21 Jul 2026.** Get all payment terminals. Use `/resources/payment-terminals/v1.1` instead.", "deprecated": true, "tags": [ "resource / payment terminals" ], "parameters": { "query": { "page": { "description": "The page number to fetch (defaults to 1)", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "serialNumber": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/payment-terminals/v1.0", "method": "POST", "operationId": "createPaymentTerminalDeprecated", "summary": "Payment Terminals / Create", "description": "**This endpoint is deprecated and will be removed on Tue, 21 Jul 2026.** Create a new payment terminal. Use `/resources/payment-terminals/v1.1` instead.", "deprecated": true, "tags": [ "resource / payment terminals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "defaultLanguage": { "type": "string" }, "displayTextTimeout": { "type": "integer" }, "displayText": { "type": "string" }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "externalId": { "type": "string", "description": "An optional external identifier for the terminal that can be used to reference it in external systems." } }, "required": [ "name", "integrationId", "terminalType", "serialNumber", "defaultLanguage", "operatorId" ], "oneOf": [ { "required": [ "preauthorizeAmount" ], "allOf": [ { "type": "object", "properties": { "preauthorizeAmount": { "type": "number", "description": "Provide a Pre-authorize amount when the terminal is linked to a single charger" }, "currencyId": { "type": "integer" }, "valueAddedTaxId": { "type": "integer", "description": "**This property is deprecated and will be removed on Fri, 01 Jan 2027.** Tax for payment terminals is derived from the operator's tax rules; when tax rules are disabled it falls back to the tariff's default tax, or to the operator's base tax when no tariff is assigned. Any value sent in create/update requests is accepted but ignored. Previously persisted values are still returned for backward compatibility but have no effect on billing." } } } ] }, { "required": [ "transactionTimeout" ], "allOf": [ { "type": "object", "properties": { "transactionTimeout": { "type": "integer", "description": "Provide a transaction timeout when the terminal is linked to a Location" } } } ] } ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "isOnline": { "type": "boolean", "description": "Use `networkStatus` instead" }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "currencyCode": { "type": "string" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "nullable": true }, "bundle": { "type": "object", "properties": { "version": { "type": "string", "example": [ "1.0.0", "1.0.1", "2.1.0" ], "description": "Desired version of the terminal android bundle. This field should be used to detect version difference between the actual one running on the terminal and the configured on the server, in order to detect if an OTA update is required." }, "downloadUrl": { "type": "string", "description": "Download link to the archived (zip) bundle version. Can be used to download the bundle and initiate the OTA update on the terminal." } } }, "networkStatusMonitoringEnabled": { "type": "boolean" }, "kioskModeEnabled": { "type": "boolean", "description": "Indicates whether kiosk mode is enabled for this terminal. For Location-mapped terminals, this is always true (Location-mapped terminals inherently operate in kiosk mode). For Single Charge Point terminals, this reflects the operator-configured setting." }, "suppressReceiptWhenInvoiceIssued": { "type": "boolean", "description": "When true, receipts are suppressed when invoices are issued for tax compliance in markets where issuing both documents for the same purchase is prohibited" }, "invoiceFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field identifier (e.g., email, name, taxId, country)" }, "required": { "type": "boolean", "description": "Whether this field is required or optional" }, "type": { "type": "string", "enum": [ "individual", "company" ], "description": "The invoice type this field belongs to (individual or company)" }, "label": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Translated label for the field. Always contains at least an English system translation entry. When custom labels are configured, they are appended after the English fallback." } }, "required": [ "field", "required", "type", "label" ] }, "description": "Invoice field configurations for ad-hoc invoicing. Only included when ad-hoc invoicing is enabled for this terminal." }, "showTermsAndConditions": { "type": "boolean", "description": "Whether Terms and Conditions should be displayed on this terminal before ad-hoc charging sessions." }, "termVersionId": { "type": "integer", "nullable": true, "description": "The ID of the active Terms version to display. Only present when showTermsAndConditions is true. Use the Terms and Policies Read endpoint to fetch the content." } }, "required": [ "phone", "defaultLanguage", "info", "bundle", "suppressReceiptWhenInvoiceIssued", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } }, "required": [ "serialNumber", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "webhookUrl": { "type": "string" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "suppressReceiptWhenInvoiceIssued": { "type": "boolean", "description": "When true, receipts are suppressed when invoices are issued for tax compliance in markets where issuing both documents for the same purchase is prohibited" } }, "required": [ "suppressReceiptWhenInvoiceIssued", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "terminalId": { "type": "string", "description": "This is the Device Number of the relevant Nayax terminal that is set up in the Nayax system. Please be careful to add the correct Device number on the relevant terminal." }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } }, "required": [ "terminalId", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } }, "required": [ "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "verificationCode": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } }, "required": [ "verificationCode", "defaultLanguage", "info", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } }, "required": [ "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "invoiceFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field identifier (e.g., email, name, taxId, country)" }, "required": { "type": "boolean", "description": "Whether this field is required or optional" }, "type": { "type": "string", "enum": [ "individual", "company" ], "description": "The invoice type this field belongs to (individual or company)" }, "label": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Translated label for the field. Always contains at least an English system translation entry. When custom labels are configured, they are appended after the English fallback." } }, "required": [ "field", "required", "type", "label" ] }, "description": "Invoice field configurations for ad-hoc invoicing. Only included when ad-hoc invoicing is enabled for this terminal." }, "suppressReceiptWhenInvoiceIssued": { "type": "boolean", "description": "When true, receipts are suppressed when invoices are issued for tax compliance in markets where issuing both documents for the same purchase is prohibited" } }, "required": [ "suppressReceiptWhenInvoiceIssued", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "currencyCode": { "type": "string" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "merchantAccount": { "type": "string", "description": "Unique identifier of the merchant in Adyen's portal" }, "adyenApiKey": { "type": "string", "description": "API key to authenticate requests to Adyen" }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "nullable": true }, "networkStatusMonitoringEnabled": { "type": "boolean" }, "kioskModeEnabled": { "type": "boolean", "description": "Indicates whether kiosk mode is enabled for this terminal. For Location-mapped terminals, this is always true (Location-mapped terminals inherently operate in kiosk mode). For Single Charge Point terminals, this reflects the operator-configured setting." }, "suppressReceiptWhenInvoiceIssued": { "type": "boolean", "description": "When true, receipts are suppressed when invoices are issued for tax compliance in markets where issuing both documents for the same purchase is prohibited" }, "invoiceFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field identifier (e.g., email, name, taxId, country)" }, "required": { "type": "boolean", "description": "Whether this field is required or optional" }, "type": { "type": "string", "enum": [ "individual", "company" ], "description": "The invoice type this field belongs to (individual or company)" }, "label": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Translated label for the field. Always contains at least an English system translation entry. When custom labels are configured, they are appended after the English fallback." } }, "required": [ "field", "required", "type", "label" ] }, "description": "Invoice field configurations for ad-hoc invoicing. Only included when ad-hoc invoicing is enabled for this terminal." }, "showTermsAndConditions": { "type": "boolean", "description": "Whether Terms and Conditions should be displayed on this terminal before ad-hoc charging sessions." }, "termVersionId": { "type": "integer", "nullable": true, "description": "The ID of the active Terms version to display. Only present when showTermsAndConditions is true. Use the Terms and Policies Read endpoint to fetch the content." } }, "required": [ "phone", "defaultLanguage", "info", "merchantAccount", "adyenApiKey", "suppressReceiptWhenInvoiceIssued", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "currencyCode": { "type": "string" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "nullable": true }, "bundle": { "type": "object", "properties": { "version": { "type": "string", "example": [ "1.0.0", "1.0.1", "2.1.0" ], "description": "Desired version of the terminal android bundle. This field should be used to detect version difference between the actual one running on the terminal and the configured on the server, in order to detect if an OTA update is required." }, "downloadUrl": { "type": "string", "description": "Download link to the archived (zip) bundle version. Can be used to download the bundle and initiate the OTA update on the terminal." } } }, "networkStatusMonitoringEnabled": { "type": "boolean" }, "kioskModeEnabled": { "type": "boolean", "description": "Indicates whether kiosk mode is enabled for this terminal. For Location-mapped terminals, this is always true (Location-mapped terminals inherently operate in kiosk mode). For Single Charge Point terminals, this reflects the operator-configured setting." }, "suppressReceiptWhenInvoiceIssued": { "type": "boolean", "description": "When true, receipts are suppressed when invoices are issued for tax compliance in markets where issuing both documents for the same purchase is prohibited" }, "invoiceFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field identifier (e.g., email, name, taxId, country)" }, "required": { "type": "boolean", "description": "Whether this field is required or optional" }, "type": { "type": "string", "enum": [ "individual", "company" ], "description": "The invoice type this field belongs to (individual or company)" }, "label": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Translated label for the field. Always contains at least an English system translation entry. When custom labels are configured, they are appended after the English fallback." } }, "required": [ "field", "required", "type", "label" ] }, "description": "Invoice field configurations for ad-hoc invoicing. Only included when ad-hoc invoicing is enabled for this terminal." }, "showTermsAndConditions": { "type": "boolean", "description": "Whether Terms and Conditions should be displayed on this terminal before ad-hoc charging sessions." }, "termVersionId": { "type": "integer", "nullable": true, "description": "The ID of the active Terms version to display. Only present when showTermsAndConditions is true. Use the Terms and Policies Read endpoint to fetch the content." } }, "required": [ "phone", "defaultLanguage", "info", "bundle", "suppressReceiptWhenInvoiceIssued", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "isOnline": { "type": "boolean", "description": "Use `networkStatus` instead" }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "currencyCode": { "type": "string" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "nullable": true }, "bundle": { "type": "object", "properties": { "version": { "type": "string", "example": [ "1.0.0", "1.0.1", "2.1.0" ], "description": "Desired version of the terminal android bundle. This field should be used to detect version difference between the actual one running on the terminal and the configured on the server, in order to detect if an OTA update is required." }, "downloadUrl": { "type": "string", "description": "Download link to the archived (zip) bundle version. Can be used to download the bundle and initiate the OTA update on the terminal." } } }, "networkStatusMonitoringEnabled": { "type": "boolean" }, "kioskModeEnabled": { "type": "boolean", "description": "Indicates whether kiosk mode is enabled for this terminal. For Location-mapped terminals, this is always true (Location-mapped terminals inherently operate in kiosk mode). For Single Charge Point terminals, this reflects the operator-configured setting." }, "suppressReceiptWhenInvoiceIssued": { "type": "boolean", "description": "When true, receipts are suppressed when invoices are issued for tax compliance in markets where issuing both documents for the same purchase is prohibited" }, "invoiceFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field identifier (e.g., email, name, taxId, country)" }, "required": { "type": "boolean", "description": "Whether this field is required or optional" }, "type": { "type": "string", "enum": [ "individual", "company" ], "description": "The invoice type this field belongs to (individual or company)" }, "label": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Translated label for the field. Always contains at least an English system translation entry. When custom labels are configured, they are appended after the English fallback." } }, "required": [ "field", "required", "type", "label" ] }, "description": "Invoice field configurations for ad-hoc invoicing. Only included when ad-hoc invoicing is enabled for this terminal." }, "showTermsAndConditions": { "type": "boolean", "description": "Whether Terms and Conditions should be displayed on this terminal before ad-hoc charging sessions." }, "termVersionId": { "type": "integer", "nullable": true, "description": "The ID of the active Terms version to display. Only present when showTermsAndConditions is true. Use the Terms and Policies Read endpoint to fetch the content." } }, "required": [ "phone", "defaultLanguage", "info", "bundle", "suppressReceiptWhenInvoiceIssued", "name", "integrationId", "terminalType", "operatorId" ] } ] } } } }, "responses": { "200": { "description": "Request succeeded" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/payment-terminals/v1.0/{paymentTerminal}", "method": "GET", "operationId": "getPaymentTerminalDeprecated", "summary": "Payment Terminals / Read", "description": "**This endpoint is deprecated and will be removed on Tue, 21 Jul 2026.** Get information for a payment terminal by ID. Use `/resources/payment-terminals/v1.1` instead.", "deprecated": true, "tags": [ "resource / payment terminals" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/payment-terminals/v1.0/{paymentTerminal}", "method": "DELETE", "operationId": "deletePaymentTerminalDeprecated", "summary": "Payment Terminals / Delete", "description": "**This endpoint is deprecated and will be removed on Tue, 21 Jul 2026.** Delete a payment terminal. Use `/resources/payment-terminals/v1.1` instead.", "deprecated": true, "tags": [ "resource / payment terminals" ], "responses": { "204": { "description": "Payment terminal deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/payment-terminals/v1.0/{paymentTerminal}", "method": "PATCH", "operationId": "updatePaymentTerminalDeprecated", "summary": "Payment Terminals / Update", "description": "**This endpoint is deprecated and will be removed on Tue, 21 Jul 2026.** Update payment terminal. Use `/resources/payment-terminals/v1.1` instead.", "deprecated": true, "tags": [ "resource / payment terminals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "defaultLanguage": { "type": "string" }, "displayTextTimeout": { "type": "integer" }, "displayText": { "type": "string" }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "externalId": { "type": "string", "description": "An optional external identifier for the terminal that can be used to reference it in external systems." } }, "oneOf": [ { "type": "object", "properties": { "preauthorizeAmount": { "type": "number", "description": "Provide a Pre-authorize amount when the terminal is linked to a single charger" }, "currencyId": { "type": "integer" }, "valueAddedTaxId": { "type": "integer", "description": "**This property is deprecated and will be removed on Fri, 01 Jan 2027.** Tax for payment terminals is derived from the operator's tax rules; when tax rules are disabled it falls back to the tariff's default tax, or to the operator's base tax when no tariff is assigned. Any value sent in create/update requests is accepted but ignored. Previously persisted values are still returned for backward compatibility but have no effect on billing." } } }, { "type": "object", "properties": { "transactionTimeout": { "type": "integer", "description": "Provide a transaction timeout when the terminal is linked to a Location" } } } ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "isOnline": { "type": "boolean", "description": "Use `networkStatus` instead" }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "nullable": true } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "webhookUrl": { "type": "string" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "terminalId": { "type": "string", "description": "This is the Device Number of the relevant Nayax terminal that is set up in the Nayax system. Please be careful to add the correct Device number on the relevant terminal." }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "verificationCode": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "merchantAccount": { "type": "string", "description": "Unique identifier of the merchant in Adyen's portal" }, "adyenApiKey": { "type": "string", "description": "API key to authenticate requests to Adyen" }, "supportedLanguages": { "type": "array", "items": { "type": "string" } }, "networkStatusMonitoringEnabled": { "type": "boolean" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "supportedLanguages": { "type": "array", "items": { "type": "string" } }, "networkStatusMonitoringEnabled": { "type": "boolean" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Ampeco", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "isOnline": { "type": "boolean", "description": "Use `networkStatus` instead" }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "nullable": true } } } ] } } } }, "responses": { "200": { "description": "Payment terminal updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/payment-terminals/v1.1", "method": "GET", "operationId": "getPaymentTerminalsV1_1", "summary": "Payment Terminals / Listing", "description": "Get all payment terminals", "tags": [ "resource / payment terminals" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "serialNumber": { "type": "string", "description": "Filter payment terminals by serial number or station." }, "customFields": { "type": "object", "additionalProperties": true, "description": "Map of administrator-defined custom field identifiers to filter values. Send each entry as `filter[customFields.]`." } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The requested custom field filter identifier is unavailable" }, "422": { "description": "The request contains invalid criteria, including malformed or non-filterable custom field filters" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/payment-terminals/v1.1", "method": "POST", "operationId": "createPaymentTerminalV1_1", "summary": "Payment Terminals / Create", "description": "Create a new payment terminal", "tags": [ "resource / payment terminals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "defaultLanguage": { "type": "string" }, "displayTextTimeout": { "type": "integer" }, "displayText": { "type": "string" }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "externalId": { "type": "string", "description": "An optional external identifier for the terminal that can be used to reference it in external systems." } }, "required": [ "name", "integrationId", "terminalType", "serialNumber", "defaultLanguage", "operatorId" ], "oneOf": [ { "required": [ "preauthorizeAmount" ], "allOf": [ { "type": "object", "properties": { "preauthorizeAmount": { "type": "number", "description": "Provide a Pre-authorize amount when the terminal is linked to a single charger" }, "currencyId": { "type": "integer" }, "valueAddedTaxId": { "type": "integer", "description": "**This property is deprecated and will be removed on Fri, 01 Jan 2027.** Tax for payment terminals is derived from the operator's tax rules; when tax rules are disabled it falls back to the tariff's default tax, or to the operator's base tax when no tariff is assigned. Any value sent in create/update requests is accepted but ignored. Previously persisted values are still returned for backward compatibility but have no effect on billing." } } } ] }, { "required": [ "transactionTimeout" ], "allOf": [ { "type": "object", "properties": { "transactionTimeout": { "type": "integer", "description": "Provide a transaction timeout when the terminal is linked to a Location" } } } ] } ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "isOnline": { "type": "boolean", "description": "Use `networkStatus` instead" }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "currencyCode": { "type": "string" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "nullable": true }, "bundle": { "type": "object", "properties": { "version": { "type": "string", "example": [ "1.0.0", "1.0.1", "2.1.0" ], "description": "The target OTA bundle version configured for this terminal (terminal-level override if set, otherwise the integration default). Pairs with `currentBundleVersion`, which reflects the version actually running on the device." }, "downloadUrl": { "type": "string", "description": "Download link to the archived (zip) bundle version." } } }, "networkStatusMonitoringEnabled": { "type": "boolean" }, "kioskModeEnabled": { "type": "boolean", "description": "Indicates whether kiosk mode is enabled for this terminal. For Location-mapped terminals, this is always true (Location-mapped terminals inherently operate in kiosk mode). For Single Charge Point terminals, this reflects the operator-configured setting." }, "simplifiedJourneyMode": { "type": "string", "enum": [ "off", "evseList", "screensaver" ], "default": "off", "example": "off", "description": "Simplified journey mode for the terminal app: - **off**: Standard multi-step journey (default) - **evseList**: Driver selects an EVSE from a list on the terminal - **screensaver**: Passive branded display; terminal auto-triggers pre-authorization when an EVSE enters Preparing status" }, "screensaverWelcomeMessage": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Translatable welcome message shown on the terminal's screensaver. Returned only when `simplifiedJourneyMode` is `screensaver`. The response value is resolved per field through a three-layer cascade: the per-terminal value if set, otherwise the integration-level default configured on the Worldline Valina/Castles integration, otherwise the property is omitted (the Terminal app falls back to its shipped default). Each translation is capped at 100 characters." }, "screensaverPaymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "visa", "mastercard", "paypal", "maestro", "amex", "bancontact", "cartes_bancaires", "diners_club", "discover", "interac", "jcb", "mada", "visa_electron", "applepay", "googlepay", "twint" ], "description": "Payment method icon displayed on the terminal's screensaver. Values cover supported card networks and digital wallet types." }, "maxItems": 8, "description": "Ordered list of payment-method icons displayed on the terminal's screensaver. Returned only when `simplifiedJourneyMode` is `screensaver`. The response value is resolved per field through a three-layer cascade: the per-terminal value if set, otherwise the integration-level default configured on the Worldline Valina/Castles integration, otherwise the property is omitted (the Terminal app resolves the icon list at boot)." }, "screensaverLogoUrl": { "type": "string", "format": "uri", "description": "URL of the uploaded screensaver logo asset. Returned only when `simplifiedJourneyMode` is `screensaver`. The response value is resolved per field through a three-layer cascade: the per-terminal value if set, otherwise the integration-level default configured on the Worldline Valina/Castles integration, otherwise the property is omitted (the Terminal app falls back to its shipped default)." }, "invoiceFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field identifier (e.g., email, name, taxId, country)" }, "required": { "type": "boolean", "description": "Whether this field is required or optional" }, "type": { "type": "string", "enum": [ "individual", "company" ], "description": "The invoice type this field belongs to (individual or company)" }, "label": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Translated label for the field. Always contains at least an English system translation entry. When custom labels are configured, they are appended after the English fallback." } }, "required": [ "field", "required", "type", "label" ] }, "description": "Invoice field configurations for ad-hoc invoicing. Only included when ad-hoc invoicing is enabled for this terminal." }, "invoiceDetailsMandatory": { "type": "boolean", "description": "Indicates whether invoice details collection is mandatory for ad-hoc charging sessions on this terminal. Only included when ad-hoc invoicing is enabled for this terminal." }, "showTermsAndConditions": { "type": "boolean", "description": "Whether Terms and Conditions should be displayed on this terminal before ad-hoc charging sessions." }, "termVersionId": { "type": "integer", "nullable": true, "description": "The ID of the active Terms version to display. Only present when showTermsAndConditions is true. Use the Terms and Policies Read endpoint to fetch the content." } }, "required": [ "phone", "defaultLanguage", "info", "bundle", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } }, "required": [ "serialNumber", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "webhookUrl": { "type": "string" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } }, "required": [ "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "terminalId": { "type": "string", "description": "This is the Device Number of the relevant Nayax terminal that is set up in the Nayax system. Please be careful to add the correct Device number on the relevant terminal." }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } }, "required": [ "terminalId", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } }, "required": [ "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "verificationCode": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } }, "required": [ "verificationCode", "defaultLanguage", "info", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } }, "required": [ "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "invoiceFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field identifier (e.g., email, name, taxId, country)" }, "required": { "type": "boolean", "description": "Whether this field is required or optional" }, "type": { "type": "string", "enum": [ "individual", "company" ], "description": "The invoice type this field belongs to (individual or company)" }, "label": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Translated label for the field. Always contains at least an English system translation entry. When custom labels are configured, they are appended after the English fallback." } }, "required": [ "field", "required", "type", "label" ] }, "description": "Invoice field configurations for ad-hoc invoicing. Only included when ad-hoc invoicing is enabled for this terminal." }, "invoiceDetailsMandatory": { "type": "boolean", "description": "Indicates whether invoice details collection is mandatory for ad-hoc charging sessions on this terminal. Only included when ad-hoc invoicing is enabled for this terminal." } }, "required": [ "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "currencyCode": { "type": "string" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "merchantAccount": { "type": "string", "description": "Unique identifier of the merchant in Adyen's portal" }, "adyenApiKey": { "type": "string", "description": "API key to authenticate requests to Adyen" }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "nullable": true }, "networkStatusMonitoringEnabled": { "type": "boolean" }, "kioskModeEnabled": { "type": "boolean", "description": "Indicates whether kiosk mode is enabled for this terminal. For Location-mapped terminals, this is always true (Location-mapped terminals inherently operate in kiosk mode). For Single Charge Point terminals, this reflects the operator-configured setting." }, "invoiceFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field identifier (e.g., email, name, taxId, country)" }, "required": { "type": "boolean", "description": "Whether this field is required or optional" }, "type": { "type": "string", "enum": [ "individual", "company" ], "description": "The invoice type this field belongs to (individual or company)" }, "label": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Translated label for the field. Always contains at least an English system translation entry. When custom labels are configured, they are appended after the English fallback." } }, "required": [ "field", "required", "type", "label" ] }, "description": "Invoice field configurations for ad-hoc invoicing. Only included when ad-hoc invoicing is enabled for this terminal." }, "invoiceDetailsMandatory": { "type": "boolean", "description": "Indicates whether invoice details collection is mandatory for ad-hoc charging sessions on this terminal. Only included when ad-hoc invoicing is enabled for this terminal." }, "showTermsAndConditions": { "type": "boolean", "description": "Whether Terms and Conditions should be displayed on this terminal before ad-hoc charging sessions." }, "termVersionId": { "type": "integer", "nullable": true, "description": "The ID of the active Terms version to display. Only present when showTermsAndConditions is true. Use the Terms and Policies Read endpoint to fetch the content." } }, "required": [ "phone", "defaultLanguage", "info", "merchantAccount", "adyenApiKey", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "currencyCode": { "type": "string" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "nullable": true }, "bundle": { "type": "object", "properties": { "version": { "type": "string", "example": [ "1.0.0", "1.0.1", "2.1.0" ], "description": "The target OTA bundle version configured for this terminal (terminal-level override if set, otherwise the integration default). Pairs with `currentBundleVersion`, which reflects the version actually running on the device." }, "downloadUrl": { "type": "string", "description": "Download link to the archived (zip) bundle version." } } }, "networkStatusMonitoringEnabled": { "type": "boolean" }, "kioskModeEnabled": { "type": "boolean", "description": "Indicates whether kiosk mode is enabled for this terminal. For Location-mapped terminals, this is always true (Location-mapped terminals inherently operate in kiosk mode). For Single Charge Point terminals, this reflects the operator-configured setting." }, "invoiceFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field identifier (e.g., email, name, taxId, country)" }, "required": { "type": "boolean", "description": "Whether this field is required or optional" }, "type": { "type": "string", "enum": [ "individual", "company" ], "description": "The invoice type this field belongs to (individual or company)" }, "label": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Translated label for the field. Always contains at least an English system translation entry. When custom labels are configured, they are appended after the English fallback." } }, "required": [ "field", "required", "type", "label" ] }, "description": "Invoice field configurations for ad-hoc invoicing. Only included when ad-hoc invoicing is enabled for this terminal." }, "invoiceDetailsMandatory": { "type": "boolean", "description": "Indicates whether invoice details collection is mandatory for ad-hoc charging sessions on this terminal. Only included when ad-hoc invoicing is enabled for this terminal." }, "showTermsAndConditions": { "type": "boolean", "description": "Whether Terms and Conditions should be displayed on this terminal before ad-hoc charging sessions." }, "termVersionId": { "type": "integer", "nullable": true, "description": "The ID of the active Terms version to display. Only present when showTermsAndConditions is true. Use the Terms and Policies Read endpoint to fetch the content." } }, "required": [ "phone", "defaultLanguage", "info", "bundle", "name", "integrationId", "terminalType", "operatorId" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "operatorId": { "type": "integer", "description": "The operator ID for this terminal." }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "isOnline": { "type": "boolean", "description": "Use `networkStatus` instead" }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "currencyCode": { "type": "string" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "nullable": true }, "bundle": { "type": "object", "properties": { "version": { "type": "string", "example": [ "1.0.0", "1.0.1", "2.1.0" ], "description": "The target OTA bundle version configured for this terminal (terminal-level override if set, otherwise the integration default). Pairs with `currentBundleVersion`, which reflects the version actually running on the device." }, "downloadUrl": { "type": "string", "description": "Download link to the archived (zip) bundle version." } } }, "networkStatusMonitoringEnabled": { "type": "boolean" }, "kioskModeEnabled": { "type": "boolean", "description": "Indicates whether kiosk mode is enabled for this terminal. For Location-mapped terminals, this is always true (Location-mapped terminals inherently operate in kiosk mode). For Single Charge Point terminals, this reflects the operator-configured setting." }, "invoiceFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field identifier (e.g., email, name, taxId, country)" }, "required": { "type": "boolean", "description": "Whether this field is required or optional" }, "type": { "type": "string", "enum": [ "individual", "company" ], "description": "The invoice type this field belongs to (individual or company)" }, "label": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Translated label for the field. Always contains at least an English system translation entry. When custom labels are configured, they are appended after the English fallback." } }, "required": [ "field", "required", "type", "label" ] }, "description": "Invoice field configurations for ad-hoc invoicing. Only included when ad-hoc invoicing is enabled for this terminal." }, "invoiceDetailsMandatory": { "type": "boolean", "description": "Indicates whether invoice details collection is mandatory for ad-hoc charging sessions on this terminal. Only included when ad-hoc invoicing is enabled for this terminal." }, "showTermsAndConditions": { "type": "boolean", "description": "Whether Terms and Conditions should be displayed on this terminal before ad-hoc charging sessions." }, "termVersionId": { "type": "integer", "nullable": true, "description": "The ID of the active Terms version to display. Only present when showTermsAndConditions is true. Use the Terms and Policies Read endpoint to fetch the content." } }, "required": [ "phone", "defaultLanguage", "info", "bundle", "name", "integrationId", "terminalType", "operatorId" ] } ] } } } }, "responses": { "200": { "description": "Request succeeded" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/payment-terminals/v1.1/{paymentTerminal}", "method": "GET", "operationId": "getPaymentTerminalV1_1", "summary": "Payment Terminals / Read", "description": "Get information for a payment terminal by ID", "tags": [ "resource / payment terminals" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/payment-terminals/v1.1/{paymentTerminal}", "method": "DELETE", "operationId": "deletePaymentTerminalV1_1", "summary": "Payment Terminals / Delete", "description": "Delete a payment terminal.", "tags": [ "resource / payment terminals" ], "responses": { "204": { "description": "Payment terminal deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/payment-terminals/v1.1/{paymentTerminal}", "method": "PATCH", "operationId": "updatePaymentTerminalV1_1", "summary": "Payment Terminals / Update", "description": "Update Payment terminal", "tags": [ "resource / payment terminals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "defaultLanguage": { "type": "string" }, "displayTextTimeout": { "type": "integer" }, "displayText": { "type": "string" }, "externalId": { "type": "string", "description": "An optional external identifier for the terminal that can be used to reference it in external systems." } }, "oneOf": [ { "type": "object", "properties": { "preauthorizeAmount": { "type": "number", "description": "Provide a Pre-authorize amount when the terminal is linked to a single charger" }, "currencyId": { "type": "integer" }, "valueAddedTaxId": { "type": "integer", "description": "**This property is deprecated and will be removed on Fri, 01 Jan 2027.** Tax for payment terminals is derived from the operator's tax rules; when tax rules are disabled it falls back to the tariff's default tax, or to the operator's base tax when no tariff is assigned. Any value sent in create/update requests is accepted but ignored. Previously persisted values are still returned for backward compatibility but have no effect on billing." } } }, { "type": "object", "properties": { "transactionTimeout": { "type": "integer", "description": "Provide a transaction timeout when the terminal is linked to a Location" } } } ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "terminalId": { "type": "string", "description": "The terminal ID assigned by the acquirer." }, "terminalModel": { "type": "string", "description": "The hardware model reported by the terminal." }, "currentBundleVersion": { "type": "string", "description": "The bundle version currently running on the terminal." }, "lastCertifiedAppVersion": { "type": "string", "description": "The last certified app version reported by the terminal." }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "isOnline": { "type": "boolean", "description": "Use `networkStatus` instead" }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "nullable": true }, "simplifiedJourneyMode": { "type": "string", "enum": [ "off", "evseList", "screensaver" ], "default": "off", "example": "off", "description": "Simplified journey mode for the terminal app: - **off**: Standard multi-step journey (default) - **evseList**: Driver selects an EVSE from a list on the terminal - **screensaver**: Passive branded display; terminal auto-triggers pre-authorization when an EVSE enters Preparing status" }, "screensaverWelcomeMessage": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "nullable": true, "description": "Translatable welcome message shown on the terminal's screensaver. Writable only when the resulting `simplifiedJourneyMode` (after applying this request) is `screensaver`. Each translation is capped at 100 characters." }, "screensaverPaymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "visa", "mastercard", "paypal", "maestro", "amex", "bancontact", "cartes_bancaires", "diners_club", "discover", "interac", "jcb", "mada", "visa_electron", "applepay", "googlepay", "twint" ], "description": "Payment method icon displayed on the terminal's screensaver. Values cover supported card networks and digital wallet types." }, "maxItems": 8, "nullable": true, "description": "Ordered list of payment-method icons displayed on the terminal's screensaver. Writable only when the resulting `simplifiedJourneyMode` (after applying this request) is `screensaver`. Values outside the selectable list are rejected." } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "webhookUrl": { "type": "string" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "terminalId": { "type": "string", "description": "This is the Device Number of the relevant Nayax terminal that is set up in the Nayax system. Please be careful to add the correct Device number on the relevant terminal." }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "verificationCode": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "terminalId": { "type": "string", "description": "The terminal ID assigned by the acquirer." }, "terminalModel": { "type": "string", "description": "The hardware model reported by the terminal." }, "currentBundleVersion": { "type": "string", "description": "The bundle version currently running on the terminal." }, "lastCertifiedAppVersion": { "type": "string", "description": "The last certified app version reported by the terminal." }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "merchantAccount": { "type": "string", "description": "Unique identifier of the merchant in Adyen's portal" }, "adyenApiKey": { "type": "string", "description": "API key to authenticate requests to Adyen" }, "supportedLanguages": { "type": "array", "items": { "type": "string" } }, "networkStatusMonitoringEnabled": { "type": "boolean" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "terminalId": { "type": "string", "description": "The terminal ID assigned by the acquirer." }, "terminalModel": { "type": "string", "description": "The hardware model reported by the terminal." }, "currentBundleVersion": { "type": "string", "description": "The bundle version currently running on the terminal." }, "lastCertifiedAppVersion": { "type": "string", "description": "The last certified app version reported by the terminal." }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "supportedLanguages": { "type": "array", "items": { "type": "string" } }, "networkStatusMonitoringEnabled": { "type": "boolean" } } }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "integrationId": { "type": "integer" }, "terminalType": { "type": "string", "enum": [ "Payter", "Valina", "Crane", "Generic", "Nayax", "Embedded", "Pax", "Windcave", "Web portal", "AdyenCastles", "Adyen Castles", "Printec Castles", "Cardlink Castles" ] }, "chargingZoneId": { "type": "integer", "description": "The charging zone the terminal belongs to. Note that either the `chargePointId` OR this attribute should be provided;" }, "chargePointId": { "type": "integer", "description": "The Charge point the terminal belongs to. Note that either the `chargingZoneId` OR this attribute should be provided;" }, "terminalId": { "type": "string", "description": "The terminal ID assigned by the acquirer." }, "terminalModel": { "type": "string", "description": "The hardware model reported by the terminal." }, "currentBundleVersion": { "type": "string", "description": "The bundle version currently running on the terminal." }, "lastCertifiedAppVersion": { "type": "string", "description": "The last certified app version reported by the terminal." }, "adminToken": { "type": "string", "description": "Specific token, linked to each terminal that can be used for access to the API. The token is created automatically when a new payment terminal is created." }, "isOnline": { "type": "boolean", "description": "Use `networkStatus` instead" }, "networkStatus": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "phone": { "type": "string" }, "defaultLanguage": { "type": "string" }, "presentCardOnStopSession": { "type": "boolean", "default": false }, "info": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } } }, "serialNumber": { "type": "string" }, "externalId": { "type": "string" }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "nullable": true } } } ] } } } }, "responses": { "200": { "description": "Payment terminal updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/provisioning-certificates/v2.0", "method": "GET", "operationId": "listPcIds", "summary": "Provisioning Certificate / Listing", "description": "Get all Provisioning Certificates", "tags": [ "resource / provisioning certificate" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/provisioning-certificates/v2.0", "method": "POST", "operationId": "createPcId", "summary": "Provisioning Certificate / Create", "description": "Create Provisioning Certificate", "tags": [ "resource / provisioning certificate" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "pcId": { "type": "string" }, "name": { "type": "string" }, "vehicleType": { "type": "string", "enum": [ "company", "private" ] }, "userId": { "type": "integer" } }, "required": [ "pcId", "name", "vehicleType", "userId" ] } } } }, "responses": { "201": { "description": "Provisioning Certificate created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/provisioning-certificates/v2.0/{provisioningCertificate}", "method": "GET", "operationId": "getPcId", "summary": "Provisioning Certificate / Read", "description": "Get a Provisioning Certificate", "tags": [ "resource / provisioning certificate" ], "responses": { "200": { "description": "Provisioning Certificate returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/provisioning-certificates/v2.0/{provisioningCertificate}", "method": "DELETE", "operationId": "deletePcId", "summary": "Provisioning Certificates / Delete", "description": "Delete a provisioning certificate.", "tags": [ "resource / provisioning certificate" ], "responses": { "204": { "description": "Provisioning certificate deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/provisioning-certificates/v2.0/{provisioningCertificate}", "method": "PATCH", "operationId": "updatePcId", "summary": "Provisioning Certificate / Update", "description": "Update a Provisioning Certificate", "tags": [ "resource / provisioning certificate" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "pcId": { "type": "string" }, "name": { "type": "string" }, "vehicleType": { "type": "string", "enum": [ "company", "private" ] }, "userId": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Provisioning Certificate updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/receipts/v2.0", "method": "GET", "operationId": "receiptsListing", "summary": "Receipts / Listing", "description": "Get all receipts", "tags": [ "resource / receipts" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "userId": { "type": "string", "format": "integer", "description": "Only list Receipts with a certain user id" }, "taxId": { "type": "string", "format": "integer", "description": "Only list Receipts with specific VAT id" }, "paymentStatus": { "type": "string", "enum": [ "pending", "paid", "partially_paid" ] }, "partnerId": { "type": "string", "format": "integer", "description": "Only list Receipts issued from a specific Partner" }, "periodStart": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" }, "periodEnd": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" }, "issuedFrom": { "type": "string", "format": "date", "description": "Filter receipts issued on or after this date (inclusive)" }, "issuedTo": { "type": "string", "format": "date", "description": "Filter receipts issued on or before this date (inclusive)" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/receipts/v2.0/{receipt}", "method": "GET", "operationId": "receiptRead", "summary": "Receipt / Read", "description": "Get a single receipt", "tags": [ "resource / receipts" ], "parameters": { "path": { "receipt": { "description": "The Receipt ID", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/reimbursement-policies/v1.0", "method": "GET", "operationId": "reimbursementPoliciesListing", "summary": "Reimbursement policies / Listing", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Get all reimbursement policies.", "tags": [ "resource / reimbursement policies" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "partnerId": { "type": "integer" }, "isActive": { "type": "boolean", "description": "When `true`, returns only policies that are active today (the current date falls within the `validityStartsOn`/`validityEndsOn` window). When `false`, returns only policies that are not active today." }, "electricityRateSource": { "type": "string", "enum": [ "policy", "charge_point", "integration" ], "description": "Origin of the per-kWh rate used to reimburse a home-charging session: - **policy**: The electricity rate linked to the policy provides the rate. `electricityRateId` is required and must belong to the same operator as the policy. - **charge_point**: The electricity rate assigned to the personal charge point provides the rate, whichever surface assigned it. `electricityRateId` must not be set on the policy. - **integration**: An integration resolves the electricity rate — for example by the charge point's region. The integration and its region-to-rate bindings are configured in the admin panel. `electricityRateId` is not set on the policy." } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/reimbursement-policies/v1.0", "method": "POST", "operationId": "reimbursementPolicyCreate", "summary": "Reimbursement policy / Create", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Create a reimbursement policy.", "tags": [ "resource / reimbursement policies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "validityStartsOn": { "type": "string", "format": "date", "description": "Uses the YYYY-MM-DD date format." }, "partnerId": { "type": "integer", "description": "Partner the policy is scoped to. When not set, the policy applies to every partner of the operator." }, "partnerContractId": { "type": "integer", "description": "Partner contract the policy is scoped to. Required whenever `partnerId` is set, and must belong to that partner. Policies without a partner are not scoped to a contract." }, "electricityRateId": { "type": "integer", "description": "Linked electricity rate providing the reimbursement rate. Set only when `electricityRateSource` is `policy`, where it is required." }, "validityEndsOn": { "type": "string", "format": "date", "description": "Uses the YYYY-MM-DD date format." }, "electricityRateSource": { "type": "string", "enum": [ "policy", "charge_point" ], "description": "Origin of the per-kWh rate used to reimburse a home-charging session: - **policy**: The electricity rate linked to the policy provides the rate. `electricityRateId` is required and must belong to the same operator as the policy. - **charge_point**: The electricity rate assigned to the personal charge point provides the rate, whichever surface assigned it. `electricityRateId` must not be set on the policy. The `integration` source is not writable through this API: it cannot be submitted on create or update. Policies using it are configured in the admin panel." }, "operatorId": { "type": "integer", "example": 1, "description": "Required for global admin tokens. Omit for operator-scoped tokens (defaults to the token's operator)." } }, "required": [ "name", "electricityRateSource", "validityStartsOn" ], "description": "Reimbursement policy create schema. The policy defines how a home-charging session's reimbursement rate is resolved and the validity window during which it applies." } } } }, "responses": { "201": { "description": "Created" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/reimbursement-policies/v1.0/{reimbursementPolicy}", "method": "GET", "operationId": "reimbursementPolicyRead", "summary": "Reimbursement policy / Read", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Get a single reimbursement policy.", "tags": [ "resource / reimbursement policies" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/reimbursement-policies/v1.0/{reimbursementPolicy}", "method": "DELETE", "operationId": "reimbursementPolicyDelete", "summary": "Reimbursement policy / Delete", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Delete a reimbursement policy. Deletion is rejected only while the policy is attached to partner invites. A policy is deletable whatever its `electricityRateSource` is, `integration` included; the restrictions on submitting `electricityRateSource` are described on the create and update operations and do not apply here.", "tags": [ "resource / reimbursement policies" ], "responses": { "204": { "description": "No content" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/reimbursement-policies/v1.0/{reimbursementPolicy}", "method": "PATCH", "operationId": "reimbursementPolicyUpdate", "summary": "Reimbursement policy / Update", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Update a reimbursement policy. The update is rejected with 409 while the requested change conflicts with the rate the policy resolves — selecting the `charge_point` rate source while an attached charge point has no electricity rate. That conflict clears only when the configuration changes: give the charge point a rate, or detach it from the policy. A policy whose stored `electricityRateSource` is `integration` is updated through this API like any other policy, except that its rate source cannot be changed: a request that submits `electricityRateSource` on such a policy is rejected with 409, because the integration that resolves its rate is configured in the admin panel and the binding could not be restored through this API. Omit `electricityRateSource` to update `name`, the validity dates or the partner scope. Every other rejection of the request body is reported as 422, keyed by the offending field — malformed or invalid field values, and changing `partnerId` on a policy that is already assigned to partner invites or has active charge point attachments, which returns a `partnerId` validation error rather than a 409. Deactivated attachments do not block the change.", "tags": [ "resource / reimbursement policies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "validityStartsOn": { "type": "string", "format": "date", "description": "Uses the YYYY-MM-DD date format." }, "electricityRateSource": { "type": "string", "enum": [ "policy", "charge_point" ], "description": "Origin of the per-kWh rate used to reimburse a home-charging session: - **policy**: The electricity rate linked to the policy provides the rate. `electricityRateId` is required and must belong to the same operator as the policy. - **charge_point**: The electricity rate assigned to the personal charge point provides the rate, whichever surface assigned it. `electricityRateId` must not be set on the policy. The `integration` source is not writable through this API: it cannot be submitted on create or update. Policies using it are configured in the admin panel." }, "partnerId": { "type": "integer", "nullable": true, "description": "Partner the policy is scoped to. Set to `null` to apply the policy to every partner of the operator. Clearing the partner also clears `partnerContractId`." }, "partnerContractId": { "type": "integer", "nullable": true, "description": "Partner contract the policy is scoped to. Required whenever `partnerId` is set, and must belong to that partner, so it cannot be set to `null` while the policy has a partner — clear `partnerId` instead, which clears the contract with it. These rules are enforced when `partnerId` or `partnerContractId` is changed; an update that leaves both unchanged is accepted as is." }, "electricityRateId": { "type": "integer", "nullable": true, "description": "Linked electricity rate providing the reimbursement rate. Required when `electricityRateSource` is `policy`; set to `null` (or omit) otherwise." }, "validityEndsOn": { "type": "string", "format": "date", "nullable": true, "description": "Date (inclusive) until which the policy is valid, in the YYYY-MM-DD date format. Set to `null` to remove the end date. Must be after `validityStartsOn`." } }, "description": "Reimbursement policy update schema. The policy defines how a home-charging session's reimbursement rate is resolved and the validity window during which it applies." } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/reimbursement-records/v1.0", "method": "GET", "operationId": "reimbursementRecordsListing", "summary": "Reimbursement records / Listing", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Get all reimbursement records. A record is one immutable computed reimbursement entry per charging session, including the reversing (credit) records that cancel earlier entries. For the periodic aggregates that group these records per beneficiary, payer and period, use the reimbursement reports listing.", "tags": [ "resource / reimbursement records" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "sessionId": { "type": "integer" }, "reportId": { "type": "integer", "description": "Constituent records of a reimbursement report." }, "beneficiaryUserId": { "type": "integer" }, "payerPartnerId": { "type": "integer" }, "payerOperatorId": { "type": "integer" }, "payerPartnerContractId": { "type": "integer" }, "isCredited": { "type": "boolean", "description": "true returns records that have been reversed by a credit record; false returns records not yet reversed. Reversing (credit) records themselves match false." }, "periodFrom": { "type": "string", "format": "date", "description": "Return records whose period overlaps on or after this date." }, "periodTo": { "type": "string", "format": "date", "description": "Return records whose period overlaps on or before this date." } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/reimbursement-records/v1.0/{reimbursementRecord}", "method": "GET", "operationId": "reimbursementRecordRead", "summary": "Reimbursement record / Read", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Get a single reimbursement record — the immutable computed reimbursement entry for one charging session.", "tags": [ "resource / reimbursement records" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/reimbursement-reports/v1.0", "method": "GET", "operationId": "reimbursementReportsListing", "summary": "Reimbursement reports / Listing", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Get all reimbursement reports. A report is a periodic aggregate that groups the reimbursement records sharing a beneficiary, payer and period, and exposes their totals. For the per-session entries behind those totals, use the reimbursement records listing.", "tags": [ "resource / reimbursement reports" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "reimbursementType": { "type": "string", "enum": [ "company", "private", "public" ], "example": "company", "description": "The home-charging reimbursement classification of the session: - **company**: The session is reimbursed as company charging. - **private**: The session is reimbursed as private charging. - **public**: The session is reimbursed as public charging." }, "beneficiaryUserId": { "type": "integer" }, "payerPartnerContractId": { "type": "integer" }, "payerPartnerId": { "type": "integer" }, "payerOperatorId": { "type": "integer" }, "reimbursementPolicyId": { "type": "integer" }, "periodFrom": { "type": "string", "format": "date", "description": "Return reports whose period overlaps on or after this date." }, "periodTo": { "type": "string", "format": "date", "description": "Return reports whose period overlaps on or before this date." } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/reimbursement-reports/v1.0/{reimbursementReport}", "method": "GET", "operationId": "reimbursementReportRead", "summary": "Reimbursement report / Read", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Get a single reimbursement report — the periodic aggregate over the reimbursement records sharing a beneficiary, payer and period. The report exposes its aggregated totals; its constituent records can be fetched from the reimbursement records listing via `filter[reportId]`.", "tags": [ "resource / reimbursement reports" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/reservations/v1.0", "method": "GET", "operationId": "reservationsListing", "summary": "Reservations / Listing", "description": "Get all reservations", "tags": [ "resource / reservations" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "evseId": { "type": "string", "format": "integer", "description": "Only list reservations for specific EVSE by ID" }, "userId": { "type": "string", "format": "integer", "description": "Only list reservations for a specific user by ID" }, "status": { "type": "string", "enum": [ "active", "expired", "canceled", "done" ], "description": "Only list reservations with this status" }, "reservedFrom": { "type": "string", "format": "date-time", "description": "Date from based on reserved at attribute" }, "reservedTo": { "type": "string", "format": "date-time", "description": "Date to based on reserved at attribute" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/reservations/v1.0/{reservation}", "method": "GET", "operationId": "reservationRead", "summary": "Reservation / Read", "description": "Get information for a reservation by ID", "tags": [ "resource / reservations" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/rfid-tags/v1.0", "method": "GET", "operationId": "rfidTagsListingDeprecated", "summary": "RFID Tags / Listing", "description": "Get all rfid tags", "deprecated": true, "tags": [ "resource / rfids" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "rfidTagUid": { "type": "string", "format": "integer", "description": "Only list RFID tags with a certain UID" }, "rfidLabel": { "type": "string", "description": "Only list RFID tags with a certain label" }, "userId": { "type": "string", "format": "integer", "description": "Only list RFID tags with a certain user id" }, "expireAt": { "type": "string", "format": "date-time", "description": "Only list RFID tags that have an expiration date grater or equal to the supplied date" }, "status": { "type": "string", "enum": [ "active", "disabled", "suspended" ], "description": "Only list RFID tags in this status" }, "type": { "type": "string", "enum": [ "rfid", "mac_address", "emaid" ], "description": "Only list RFID tags in this type" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/rfid-tags/v1.0", "method": "POST", "operationId": "rfidTagCreateDeprecated", "summary": "RFID Tag / Create", "description": "Create new RFID Tag", "deprecated": true, "tags": [ "resource / rfids" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "rfidTagUid": { "type": "string", "example": 123456, "description": "Token used for authorization" }, "rfidLabel": { "type": "string", "nullable": true, "description": "Visual label on the card" }, "expireAt": { "type": "string", "format": "date", "nullable": true }, "createdAt": { "type": "string", "format": "datatime" }, "status": { "type": "string", "enum": [ "enabled", "disabled", "suspended" ], "description": "The status of the RFID tag. Use it to disable or suspend a tag * `enabled` The tag is enabled and is accepted as authentication method * `disabled` The tag is disabled by the admin user and is not acceptable as authorization method * `suspended` The tag is suspended by the owner of the tag and is not acceptable as authorization method" }, "userId": { "type": "integer", "nullable": true, "description": "Associate the RFID tag with a user account. If the user is not presented, the tag will not be authorized! It makes sense to prepare the tags in advance, in case there is another process/entity is going to later assign them!" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "rfidTagUid", "status" ] } } } }, "responses": { "201": { "description": "RFID Tag created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/rfid-tags/v1.0/{rfidTag}", "method": "GET", "operationId": "rfidTagReadDeprecated", "summary": "RFID Tag / Read", "description": "Get a RFID Tag", "deprecated": true, "tags": [ "resource / rfids" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/rfid-tags/v1.0/{rfidTag}", "method": "DELETE", "operationId": "rfidTagDeleteDeprecated", "summary": "RFID Tag / Delete", "description": "Delete a RFID Tag", "deprecated": true, "tags": [ "resource / rfids" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/rfid-tags/v1.0/{rfidTag}", "method": "PATCH", "operationId": "rfidTagUpdateDeprecated", "summary": "RFID Tag / Update", "description": "Update a RFID Tag", "deprecated": true, "tags": [ "resource / rfids" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "rfidTagUid": { "type": "string", "example": 123456, "description": "Token used for authorization" }, "rfidLabel": { "type": "string", "nullable": true, "description": "Visual label on the card" }, "expireAt": { "type": "string", "format": "date", "nullable": true }, "createdAt": { "type": "string", "format": "datatime" }, "status": { "type": "string", "enum": [ "enabled", "disabled", "suspended" ], "description": "The status of the RFID tag. Use it to disable or suspend a tag * `enabled` The tag is enabled and is accepted as authentication method * `disabled` The tag is disabled by the admin user and is not acceptable as authorization method * `suspended` The tag is suspended by the owner of the tag and is not acceptable as authorization method" }, "userId": { "type": "integer", "nullable": true, "description": "Associate the RFID tag with a user account. If the user is not presented, the tag will not be authorized! It makes sense to prepare the tags in advance, in case there is another process/entity is going to later assign them!" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "rfidTagUid", "status" ] } } } }, "responses": { "200": { "description": "RFID Tag updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-connections/v2.0", "method": "GET", "operationId": "listRoamingConnections", "summary": "Roaming Connections / Listing", "description": "Get all Roaming Connections", "tags": [ "resource / roaming connections" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-connections/v2.0/{roamingConnection}", "method": "GET", "operationId": "getRoamingConnection", "summary": "Roaming Connections / Read", "description": "Get a Roaming Connections", "tags": [ "resource / roaming connections" ], "parameters": { "path": { "roamingConnection": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-cpos/v1.0", "method": "GET", "operationId": "roamingCposListing", "summary": "Roaming CPOs / Listing", "description": "Get all Roaming CPOs", "tags": [ "resource / roaming cpos" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-cpos/v1.0/{roamingCpo}", "method": "GET", "operationId": "roamingCpoRead", "summary": "Roaming CPO / Read", "description": "Get a Roaming CPO", "tags": [ "resource / roaming cpos" ], "parameters": { "path": { "roamingCpo": { "description": "The ID of the roaming CPO", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-cpos/v1.0/{roamingCpo}", "method": "PATCH", "operationId": "roamingCpoUpdate", "summary": "Roaming CPO / Update", "description": "Update Roaming CPO", "tags": [ "resource / roaming cpos" ], "parameters": { "path": { "roamingCpo": { "description": "The ID of the roaming CPO", "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "businessName": { "type": "string", "nullable": true, "description": "Business name of the CPO" }, "enabled": { "type": "boolean", "description": "Whether the CPO is enabled for roaming" }, "cpoSettings": { "type": "object", "properties": { "cpoQrCodePrefix": { "type": "string", "nullable": true, "description": "Example - \"http://m.intercharge.eu/qr?evseid=\" if the URL in the QR Code is http://m.intercharge.eu/qr?evseid=CH*ION*E213604" }, "tariffMappingMode": { "type": "string", "enum": [ "per_roaming_tariff", "per_evse", "single_tariff_group" ], "default": "per_roaming_tariff", "description": "Selects how tariff groups are assigned to this roaming partner's EVSEs. - `per_roaming_tariff`: each EVSE inherits the tariff group via the `RoamingTariff.tariffGroupId` of the roaming tariff it receives (see `/resources/roaming-tariffs`). - `per_evse`: a tariff group is assigned individually to each EVSE. - `single_tariff_group`: one tariff group is applied to all of this partner's EVSEs — useful when that group contains a \"Roaming pricing plus markup\" tariff. The underlying `tariff_mapping_mode` column is nullable; `null` falls back to `per_roaming_tariff` (the documented default). The API resolves the fallback before returning, so responses always carry one of the three values." }, "applyCustomTariffsToEvsesWithRoamingTariff": { "type": "boolean", "default": false }, "sendsPeriodicMeterUpdates": { "type": "boolean", "default": true }, "externalTariffIntegration": { "type": "string", "enum": [ "has.to.be" ], "nullable": true, "description": "External vendor identifier for an alternative tariff source. Currently the platform only supports the `has.to.be` integration." }, "treatEvseStatusUnknownAs": { "type": "string", "enum": [ "available", "unavailable" ], "default": "available", "description": "How the platform should treat an EVSE whose status received from the CPO is `unknown`. - `available`: assume the EVSE is available and surface it to drivers as such. - `unavailable`: assume the EVSE is unavailable and hide it from drivers." }, "phaseAcPowerFormula": { "type": "string", "enum": [ "amperage_voltage_3", "amperage_voltage_sqr3" ], "default": "amperage_voltage_3", "description": "Formula used to derive AC power from amperage and voltage for this CPO's EVSEs. - `amperage_voltage_3`: P = U × I × 3 (sum of per-phase products — the platform default). - `amperage_voltage_sqr3`: P = U × I × √3 (line-to-line product for balanced three-phase)." } } } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-emsps/v1.0", "method": "GET", "operationId": "roamingEmspsListing", "summary": "Roaming EMSPs / Listing", "description": "Get all Roaming EMSPs", "tags": [ "resource / roaming emsps" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "connectionId": { "type": "integer", "description": "Filter EMSPs by the ID of the roaming connection they belong to." }, "countryCode": { "type": "string", "description": "Filter EMSPs by their country code (exact match, ISO 3166-1 alpha-2)." }, "partyId": { "type": "string", "description": "Filter EMSPs by their roaming party ID (exact match)." } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-emsps/v1.0", "method": "POST", "operationId": "roamingEmspCreate", "summary": "Roaming EMSP / Create", "description": "Create new Roaming EMSP **Only applicable for Hubject OICP, Gireve 2.2.1 and OCPI with missing credentials module emsp roaming connections**", "tags": [ "resource / roaming emsps" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "businessName": { "type": "string", "description": "Business name of the EMSP" }, "connectionId": { "type": "integer", "description": "ID of the roaming connection (see /resources/roaming-connections)" }, "hubjectId": { "type": "string", "description": "Hubject Provider ID assigned to the EMSP" } }, "required": [ "connectionId" ] }, { "type": "object", "properties": { "businessName": { "type": "string", "description": "Business name of the EMSP" }, "connectionId": { "type": "integer", "description": "ID of the roaming connection (see /resources/roaming-connections)" }, "countryCode": { "type": "string", "description": "The code provided during the token exchange process" }, "partyId": { "type": "string", "description": "Roaming party ID of the EMSP" } }, "required": [ "connectionId", "countryCode", "partyId" ] } ] } } } }, "responses": { "201": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-emsps/v1.0/{roamingEmsp}", "method": "GET", "operationId": "roamingEmspRead", "summary": "Roaming EMSP / Read", "description": "Get a Roaming EMSP", "tags": [ "resource / roaming emsps" ], "parameters": { "path": { "roamingEmsp": { "description": "The ID of the roaming EMSP", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-emsps/v1.0/{roamingEmsp}", "method": "DELETE", "operationId": "roamingEmspDelete", "summary": "Roaming EMSP / Delete", "description": "Delete a Roaming EMSP", "tags": [ "resource / roaming emsps" ], "parameters": { "path": { "roamingEmsp": { "description": "The ID of the roaming EMSP", "type": "integer", "required": true } } }, "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "405": { "description": "Feature disabled for the system" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-emsps/v1.0/{roamingEmsp}", "method": "PATCH", "operationId": "roamingEmspUpdate", "summary": "Roaming EMSP / Update", "description": "Update Roaming EMSP", "tags": [ "resource / roaming emsps" ], "parameters": { "path": { "roamingEmsp": { "description": "The ID of the roaming EMSP", "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "businessName": { "type": "string", "nullable": true, "description": "Business name of the EMSP" }, "hubjectId": { "type": "string", "nullable": true, "description": "Hubject Provider ID assigned to the EMSP" } } }, { "type": "object", "properties": { "businessName": { "type": "string", "nullable": true, "description": "Business name of the EMSP" }, "countryCode": { "type": "string", "description": "The code provided during the token exchange process" }, "partyId": { "type": "string", "description": "Roaming party ID of the EMSP" } } } ] } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-emsps/v1.0/{roamingEmsp}/partners", "method": "GET", "operationId": "roamingEmspPartnersListing", "summary": "Roaming EMSP Partners / Listing", "description": "List the partner assigned to this Roaming EMSP for each platform operator. `partnerId` is `null` when no partner is assigned. Use `POST /actions/roaming-emsp/v1.0/{roamingEmsp}/assign-partner` to assign or clear a partner.", "tags": [ "resource / roaming emsps" ], "parameters": { "path": { "roamingEmsp": { "description": "The ID of the roaming EMSP", "type": "integer", "required": true } }, "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "description": "Filter assignments by platform operator id." } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-operators/v2.0", "method": "GET", "operationId": "roamingOperatorsListing", "summary": "Roaming Operators / Listing", "description": "**This endpoint is deprecated and will be removed on Fri, 30 Oct 2026.** Use `/resources/roaming-cpos/v1.0` instead. Get all Roaming Operators", "deprecated": true, "tags": [ "resource / roaming operators" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-operators/v2.0/{roamingOperator}", "method": "GET", "operationId": "roamingOperatorRead", "summary": "Roaming Operator / Read", "description": "**This endpoint is deprecated and will be removed on Fri, 30 Oct 2026.** Use `/resources/roaming-cpos/v1.0/{roamingCpo}` instead. Get a Roaming Operator", "deprecated": true, "tags": [ "resource / roaming operators" ], "parameters": { "path": { "roamingOperator": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-operators/v2.0/{roamingOperator}", "method": "PATCH", "operationId": "roamingOperatorUpdate", "summary": "Roaming Operator / Update", "description": "**This endpoint is deprecated and will be removed on Fri, 30 Oct 2026.** Use `/resources/roaming-cpos/v1.0/{roamingCpo}` instead. Update Roaming Operator", "deprecated": true, "tags": [ "resource / roaming operators" ], "parameters": { "path": { "roamingOperator": { "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "businessName": { "type": "string", "nullable": true }, "partnerId": { "type": "integer", "nullable": true, "description": "If a non-null value is provided, it will set enabled to true. If null is provided, it will set enabled to false." }, "enabled": { "type": "boolean" }, "cpoSettings": { "type": "object", "properties": { "cpoQrcodePrefix": { "type": "string", "nullable": true, "description": "Example - \"http://m.intercharge.eu/qr?evseid=\" if the URL in the QR Code is http://m.intercharge.eu/qr?evseid=CH*ION*E213604" }, "manualEvseManagement": { "type": "boolean", "default": false, "nullable": true }, "applyCustomTariffsToEvsesWithRoamingTariff": { "type": "boolean", "default": false, "nullable": true }, "sendsPeriodicMeterUpdates": { "type": "boolean", "default": true, "nullable": true }, "externalTariffIntegration": { "type": "string", "nullable": true, "description": "Only possible value is `has.to.be`" }, "threatEvseStatusUnknownAs": { "type": "string", "enum": [ "available", "unavailable" ] }, "phaseAcPowerFormula": { "type": "string", "enum": [ "amperage_voltage_3", "amperage_voltage_sqr3" ], "default": "amperage_voltage_3" } }, "nullable": true } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-operators/v2.0/{roamingOperator}/custom-tariff-filters", "method": "GET", "operationId": "listRoamingCustomTariffFilters", "summary": "Roaming Operators / Custom Tariff Filters / Listing", "description": "Get all custom tariff filters for a roaming operator", "tags": [ "resource / roaming operators" ], "parameters": { "query": { "filter": { "description": "Filter options for custom tariff filters", "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "enabled", "disabled" ], "example": "enabled", "description": "Filter by status (enabled or disabled)" }, "createdAfter": { "type": "string", "format": "date-time", "description": "Filter by creation date (greater than or equal to)" }, "createdBefore": { "type": "string", "format": "date-time", "description": "Filter by creation date (less than or equal to)" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "List of custom tariff filters" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-operators/v2.0/{roamingOperator}/custom-tariff-filters", "method": "POST", "operationId": "createRoamingCustomTariffFilter", "summary": "Roaming Operators / Custom Tariff Filters / Create", "description": "Create new custom tariff filter for a roaming operator", "tags": [ "resource / roaming operators" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the tariff filter" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code" }, "applicableCurrentTypes": { "type": "array", "items": { "type": "string", "enum": [ "AC", "DC" ] }, "description": "Array of current types (AC, DC) that this filter applies to, pass an empty array to clear all current type restrictions." }, "powerBelowKw": { "type": "number", "minimum": 0, "description": "Filter EVSEs with power below specified kW value" }, "evseIdPrefix": { "type": "string", "maxLength": 1000, "description": "Filter EVSEs whose IDs start with specified prefix(es). Multiple prefixes separated by newlines" }, "order": { "type": "integer", "description": "Position of the tariff filter in the ordering sequence. When not provided during creation, it will go last. If an already existing order number is provided, it will reorder the other tariff filters to take their place in the sequence." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "name", "status" ] } } } }, "responses": { "201": { "description": "Custom tariff filter created successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-operators/v2.0/{roamingOperator}/custom-tariff-filters/reorder", "method": "PUT", "operationId": "reorderRoamingCustomTariffFilters", "summary": "Roaming Operators / Custom Tariff Filters / Reorder", "description": "Change the ordering of custom tariff filters for a roaming operator. This operation allows partial reordering - you only need to specify the filters that need to move. Filters not included in the request will maintain their relative positions. The atomic operation prevents inconsistent states during reordering.", "tags": [ "resource / roaming operators" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 2, "description": "The ID of the custom tariff filter" }, "order": { "type": "integer", "minimum": 1, "example": 1, "description": "The new position for this filter (starting from 1)" } }, "required": [ "id", "order" ] }, "description": "Array of custom tariff filter IDs with their new positions. Only include filters that need to be moved - others will maintain their relative positions." } }, "required": [ "filters" ], "example": { "filters": [ { "id": 2, "order": 1 }, { "id": 1, "order": 2 }, { "id": 3, "order": 3 } ] } } } } }, "responses": { "200": { "description": "Order updated successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-operators/v2.0/{roamingOperator}/custom-tariff-filters/{customTariffFilter}", "method": "GET", "operationId": "getRoamingCustomTariffFilter", "summary": "Roaming Operators / Custom Tariff Filters / Read", "description": "Get a specific custom tariff filter", "tags": [ "resource / roaming operators" ], "responses": { "200": { "description": "Custom tariff filter returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-operators/v2.0/{roamingOperator}/custom-tariff-filters/{customTariffFilter}", "method": "DELETE", "operationId": "deleteRoamingCustomTariffFilter", "summary": "Roaming Operators / Custom Tariff Filters / Delete", "description": "Delete a custom tariff filter", "tags": [ "resource / roaming operators" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-operators/v2.0/{roamingOperator}/custom-tariff-filters/{customTariffFilter}", "method": "PATCH", "operationId": "updateRoamingCustomTariffFilter", "summary": "Roaming Operators / Custom Tariff Filters / Update", "description": "Update an existing custom tariff filter", "tags": [ "resource / roaming operators" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "nullable": true, "description": "ISO 3166-1 alpha-2 country code" }, "applicableCurrentTypes": { "type": "array", "items": { "type": "string", "enum": [ "AC", "DC" ] }, "description": "Array of current types (AC, DC) that this filter applies to" }, "powerBelowKw": { "type": "number", "minimum": 0, "nullable": true, "description": "Filter EVSEs with power below specified kW value" }, "evseIdPrefix": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Filter EVSEs whose IDs start with specified prefix(es). Multiple prefixes separated by newlines" }, "order": { "type": "integer", "description": "Position of the tariff filter in the ordering sequence. If an already existing order number is provided, it will reorder the other tariff filters to take their place in the sequence." } } } } } }, "responses": { "200": { "description": "Custom tariff filter updated successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-platforms/v1.0", "method": "GET", "operationId": "roamingPlatformsListingDeprecated", "summary": "Roaming Platforms / Listing", "description": "Get all Roaming Platforms. See Roaming Connections for the list of supported protocols.", "deprecated": true, "tags": [ "resource / roaming platforms" ], "parameters": { "query": { "page": { "description": "The page number to fetch (defaults to 1)", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-platforms/v1.0/{roamingPlatform}", "method": "GET", "operationId": "roamingPlatformReadDeprecated", "summary": "Roaming Platform / Read", "description": "Get a Roaming Platform. See Roaming Connections for the list of supported protocols.", "deprecated": true, "tags": [ "resource / roaming platforms" ], "parameters": { "path": { "roamingPlatform": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-providers/v2.0", "method": "GET", "operationId": "roamingProvidersListing", "summary": "Roaming Providers / Listing", "description": "**This endpoint is deprecated and will be removed on Fri, 30 Oct 2026.** Use `/resources/roaming-emsps/v1.0` instead. Get all Roaming Providers", "deprecated": true, "tags": [ "resource / roaming providers" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "platformId": { "type": "integer" }, "countryCode": { "type": "string" }, "partyId": { "type": "string" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/roaming-providers/v2.0", "method": "POST", "operationId": "roamingProviderCreate", "summary": "Roaming Provider / Create", "description": "**This endpoint is deprecated and will be removed on Fri, 30 Oct 2026.** Use `/resources/roaming-emsps/v1.0` instead. Create new Roaming Provider **Only applicable for Hubject, Gireve 2.2.1 and OCPI with missing credentials module emsp roaming connections**", "deprecated": true, "tags": [ "resource / roaming providers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "businessName": { "type": "string", "nullable": true }, "platformId": { "type": "integer" }, "partnerId": { "type": "integer", "nullable": true }, "hubjectId": { "type": "string", "nullable": true } }, "required": [ "platformId" ] }, { "type": "object", "properties": { "businessName": { "type": "string", "nullable": true }, "platformId": { "type": "integer" }, "partnerId": { "type": "integer", "nullable": true }, "countryCode": { "type": "string", "nullable": true, "description": "The code provided during the token exchange process" }, "partyId": { "type": "string", "description": "ID of the Operator or Provider of roaming" } }, "required": [ "platformId" ] } ] } } } }, "responses": { "201": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-providers/v2.0/{roamingProvider}", "method": "GET", "operationId": "roamingProviderRead", "summary": "Roaming Provider / Read", "description": "**This endpoint is deprecated and will be removed on Fri, 30 Oct 2026.** Use `/resources/roaming-emsps/v1.0/{roamingEmsp}` instead. Get a Roaming Provider", "deprecated": true, "tags": [ "resource / roaming providers" ], "parameters": { "path": { "roamingProvider": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-providers/v2.0/{roamingProvider}", "method": "DELETE", "operationId": "roamingProviderDelete", "summary": "Roaming Provider / Delete", "description": "**This endpoint is deprecated and will be removed on Fri, 30 Oct 2026.** Use `/resources/roaming-emsps/v1.0/{roamingEmsp}` instead. Delete a Roaming Provider", "deprecated": true, "tags": [ "resource / roaming providers" ], "parameters": { "path": { "roamingProvider": { "type": "integer", "required": true } } }, "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "405": { "description": "Feature disabled for the system" } } }, { "path": "/public-api/resources/roaming-providers/v2.0/{roamingProvider}", "method": "PATCH", "operationId": "roamingProviderUpdate", "summary": "Roaming Provider / Update", "description": "**This endpoint is deprecated and will be removed on Fri, 30 Oct 2026.** Use `/resources/roaming-emsps/v1.0/{roamingEmsp}` instead. Update Roaming Providers", "deprecated": true, "tags": [ "resource / roaming providers" ], "parameters": { "path": { "roamingProvider": { "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "businessName": { "type": "string", "nullable": true }, "platformId": { "type": "integer" }, "partnerId": { "type": "integer", "nullable": true }, "hubjectId": { "type": "string", "nullable": true } } }, { "type": "object", "properties": { "businessName": { "type": "string", "nullable": true }, "platformId": { "type": "integer" }, "partnerId": { "type": "integer", "nullable": true }, "countryCode": { "type": "string", "nullable": true, "description": "The code provided during the token exchange process" }, "partyId": { "type": "string", "description": "ID of the Operator or Provider of roaming" } } } ] } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-tariffs/v2.0", "method": "GET", "operationId": "roamingTariffsListing", "summary": "Roaming Tariffs / Listing", "description": "Get all Roaming Tariffs", "tags": [ "resource / roaming tariffs" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only roaming tariffs created on or after this datetime." }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only roaming tariffs created on or before this datetime." } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/roaming-tariffs/v2.0/{roamingTariff}", "method": "GET", "operationId": "roamingTariffRead", "summary": "Roaming Tariff / Read", "description": "Get a Roaming Tariff", "tags": [ "resource / roaming tariffs" ], "parameters": { "path": { "roamingTariff": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/roaming-tariffs/v2.0/{roamingTariff}", "method": "PATCH", "operationId": "roamingTariffUpdate", "summary": "Roaming Tariff / Update", "description": "Update Roaming Tariff", "tags": [ "resource / roaming tariffs" ], "parameters": { "path": { "roamingTariff": { "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "roamingIds": { "type": "array", "items": { "type": "string" } }, "roamingTariffHumanReadable": { "type": "string", "description": "This is the human readable roaming tariff as extracted from the tariff(s) shared by the CPO." }, "rawRoamingTariffs": { "type": "array", "items": { "type": "object" }, "description": "The original roaming tariffs as provided by the CPO in the respective roaming protocol format." }, "operatorId": { "type": "integer", "description": "The ID of the Roaming Operator that provided this tariff. This refers to the Roaming Operator resource, not the CPO Operator." }, "tariffGroupId": { "type": "integer", "nullable": true, "description": "The ID of the local Tariff Group assigned to the EVSEs with this roaming tariff(s)." }, "cpoTariffGroupId": { "type": "integer", "description": "The ID of the CPO's Tariff Group associated with the internal roaming map. Only present for internal roaming tariff maps." } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/security-events-log/v2.0", "method": "GET", "operationId": "securityEventLogsListingDeprecated", "summary": "Security Events Logs / Listing", "description": "Get all Security Events Log", "deprecated": true, "tags": [ "resource / security event logs" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "FirmwareUpdated", "SettingSystemTime", "StartupOfTheDevice", "ResetOrReboot", "SecurityLogWasCleared", "MemoryExhaustion", "TamperDetectionActivated" ], "description": "Type of critical security events that are pushed from the Charge Point to the backend." }, "chargePoint": { "type": "string", "format": "integer" }, "timestampFrom": { "type": "string" }, "timestampTo": { "type": "string" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/security-events-log/v2.0/{securityEventLog}", "method": "GET", "operationId": "securityEventLogReadDeprecated", "summary": "Security Event Log / Read", "description": "Get a Security Event Log", "deprecated": true, "tags": [ "resource / security event logs" ], "responses": { "200": { "description": "Security Event Log returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/security-events/v2.0", "method": "GET", "operationId": "securityEventsListing", "summary": "Security Events / Listing", "description": "Get all Security Events", "tags": [ "resource / security events" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "FirmwareUpdated", "SettingSystemTime", "StartupOfTheDevice", "ResetOrReboot", "SecurityLogWasCleared", "MemoryExhaustion", "TamperDetectionActivated" ], "description": "Type of critical security events that are pushed from the Charge Point to the backend." }, "chargePoint": { "type": "string", "format": "integer" }, "timestampFrom": { "type": "string" }, "timestampTo": { "type": "string" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/security-events/v2.0/{securityEvent}", "method": "GET", "operationId": "securityEventRead", "summary": "Security Event / Read", "description": "Get a Security Event", "tags": [ "resource / security events" ], "responses": { "200": { "description": "Security Event returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sessions/v1.0", "method": "GET", "operationId": "sessionsListing", "summary": "Sessions / Listing", "tags": [ "resource / sessions" ], "parameters": { "query": { "withClockAlignedEnergyConsumption": { "type": "boolean", "default": false }, "clockAlignedInterval": { "schema": { "type": "integer", "enum": [ 15, 30, 60 ], "default": 15 } }, "withAuthorization": { "type": "boolean", "default": false }, "withPriceBreakdown": { "type": "boolean", "default": false }, "withChargingPeriods": { "type": "boolean", "default": false }, "withChargingPeriodsPriceBreakdown": { "description": "Must be used in combination with `withChargingPeriods` parameter.", "type": "boolean", "default": false }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "evseId": { "type": "string", "format": "integer", "description": "Only list sessions on a certain EVSE" }, "chargePointId": { "type": "string", "format": "integer", "description": "Only list sessions on a certain Charge Point" }, "evsePhysicalReference": { "type": "string", "description": "Only list sessions on a certain EVSE, identified by the phisicalReference" }, "chargePointNetworkId": { "type": "string", "description": "Only list sessions on a certain Charge Point, identified by the NetworkId" }, "reason": { "type": "string", "enum": [ "working_hours_exceeded", "timeout", "authorization_amount_reached", "new_start_transaction_received", "force_stop", "standard_stop", "energy_exceeded", "schedule_completed", "pre_authorization_failed", "system_force_stop", "time_limit", "balance_exceeded", "deauthorized", "emergencystop", "energylimitreached", "evdisconnected", "groundfault", "immediatereset", "hardreset", "local", "localoutofcredit", "masterpass", "other", "overcurrentfault", "powerloss", "powerquality", "reboot", "remote", "soclimitreached", "stoppedbyev", "timeoutlimitreached", "softreset", "unlockcommand", "no_ev_parked", "no_ev_connected", "charge_point_timeout", "charging_on_evse_not_allowed", "remote_start_failed", "no_user_for_agile_streets", "rejected", "canceled_reservation", "evse_occupied", "evse_inoperative", "failed", "not_supported", "unknown_reservation", "ev_not_connect_to_evse", "authorization_failed", "unknown_session" ] }, "chargePointBootNotificationSerialNumber": { "type": "string", "description": "Only list sessions on Charge Points with last boot notification that had this charge_point_serial_number" }, "chargePointBootNotificationVendor": { "type": "string", "description": "Only list sessions on Charge Points with last boot notification that had this vendor" }, "startedAfter": { "type": "string", "format": "date-time", "description": "Only list sessions identified by the start time being after this datetime" }, "startedBefore": { "type": "string", "format": "date-time", "description": "Only list sessions identified by the start time being before this datetime" }, "userId": { "type": "string", "format": "integer", "description": "Only list sessions by a certain user" }, "status": { "type": "string", "enum": [ "unknown", "pending", "active", "finished", "failed", "expired" ], "example": "finished", "description": "Charging session status: - **unknown**: Session status could not be determined - **pending**: Session is pending and has not started yet - **active**: Session is currently in progress - **finished**: Session has completed successfully - **failed**: Session has failed - **expired**: Session has expired" }, "endedAfter": { "type": "string", "format": "date-time", "description": "Only list sessions identified by the end time being after this datetime" }, "endedBefore": { "type": "string", "format": "date-time", "description": "Only list sessions identified by the end time being before this datetime" }, "partnerId": { "type": "string", "format": "integer", "description": "Only list sessions on charge points owned by a certain partner" }, "userPartnerId": { "type": "string", "format": "integer", "description": "Only list sessions where the user belongs to a certain partner (through accepted invites)" }, "subOperatorId": { "type": "string", "format": "integer", "description": "Only list sessions associated with partners, assigned to certain sub-operator" }, "locationId": { "type": "string", "format": "integer", "description": "Only list sessions on EVSEs belonging to charge points at the specified location" }, "idTag": { "type": "string", "description": "Only list sessions started with a specific idTag (RFID identifier or remote start identifier) A remote start identifier has the format `*XXXXXXX` where the `XXXXXXX` is the session id padded with `0`s on the left" }, "paymentType": { "type": "string", "enum": [ "tokenized", "subscription", "balance", "corporate", "terminal", "bank_transfer" ], "description": "`bank_transfer` is used for one-time bank transfers, for saved (tokenized) bank transfers use `tokenized`." }, "startedOffline": { "type": "boolean", "description": "Filter sessions by offline start status. - `true` - Return only sessions that started offline - `false` - Return only sessions that did not start offline" }, "selectedPaymentMethod": { "type": "array", "items": { "type": "string", "enum": [ "corporate", "subscription", "balance", "bank_transfer", "payment_terminal", "external", "visa", "mastercard", "maestro", "amex", "paypal", "cartes_bancaires", "diners_club", "discover", "interac", "jcb", "mada", "visa_electron", "unknown", "apple_pay", "google_pay", "twint", "bancontact", "other" ] }, "description": "Filter sessions by the payment method selected when starting the session. Supports multiselect (OR logic). **General payment types:** - `corporate` - Sessions with corporate account selected as payment method - `subscription` - Sessions with user subscription selected as payment method - `balance` - Sessions with balance selected as payment method - `bank_transfer` - Sessions with bank transfer selected as payment method - `payment_terminal` - Sessions initiated via payment terminal - `external` - Sessions with external billing **Card networks:** - `visa`, `mastercard`, `maestro`, `amex`, `paypal`, `cartes_bancaires`, `diners_club`, `discover`, `interac`, `jcb`, `mada`, `visa_electron`, `bancontact` - Sessions with the specified card network selected as payment method - `unknown` - Sessions with card selected where network is not identified **Digital wallets:** - `apple_pay`, `google_pay` - Sessions with Apple Pay or Google Pay selected as payment method - `twint` - Sessions with Twint selected as payment method - `other` - Sessions with other digital wallet selected as payment method" }, "paymentStatus": { "type": "string", "enum": [ "pending", "paid", "partially", "failed" ] }, "corporateBillingPolicyId": { "type": "string", "format": "integer", "description": "Only list sessions with corporate billing context from a snapshot of the specified corporate billing policy. Part of the experimental corporate-billing feature surface; this filter may change in place without a version bump." }, "hasCorporateBilling": { "type": "boolean", "description": "Filter sessions by persisted corporate billing context. Part of the experimental corporate-billing feature surface; this filter may change in place without a version bump. - `true` - Return sessions with a corporate billing policy snapshot, including sessions where restrictions withheld coverage. - `false` - Return sessions without a corporate billing policy snapshot." }, "taxId": { "type": "string", "format": "integer", "description": "Only list sessions with specific VAT id" }, "paymentStatusUpdatedBefore": { "type": "string", "format": "date-time", "description": "Only list sessions with payment status updated before the specified date and time. Please provide the value in ISO 8601 formatted date." }, "paymentStatusUpdatedAfter": { "type": "string", "format": "date-time", "description": "Only list sessions with payment status updated after the specified date and time. Please provide the value in ISO 8601 formatted date." }, "billingCompletedBefore": { "type": "string", "format": "date-time", "description": "Only list sessions with billing completed before the specified date and time. Please provide the value in ISO 8601 formatted date." }, "billingCompletedAfter": { "type": "string", "format": "date-time", "description": "Only list sessions with billing completed after the specified date and time. Please provide the value in ISO 8601 formatted date." }, "externalAppData": { "type": "string", "example": "filter[externalAppData.property1.property2]=value", "description": "Only list records with specific external application data. You can use a dot notation to search for nested properties. For example, `filter[externalAppData.property1.property2]=value`." }, "receiptId": { "type": "string", "format": "integer", "description": "Only list sessions with specific receipt id." }, "authorizationSource": { "type": "string", "enum": [ "roaming", "local", "third_party" ], "description": "Filter sessions based on authorization source" }, "billingStatus": { "type": "string", "enum": [ "pending", "suspended", "completed", "null" ], "description": "Only list sessions in this billing status." }, "terminalId": { "type": "string", "format": "integer", "description": "Only list sessions with transaction(s) with specific payment terminal id." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the specific resource that was last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the specific resource that was last updated on and before this datetime" }, "roaming": { "type": "object", "properties": { "roamingOperatorCpoIds": { "type": "array", "items": { "type": "integer" }, "description": "Only list sessions initiated on the EVSEs of a specific Roaming operator with a CPO role." }, "roamingOperatorEmspIds": { "type": "array", "items": { "type": "integer" }, "description": "Filter sessions by the EMSP operator that authorized the session. Accepts one or more roaming operator IDs with EMSP role." }, "roamingConnectionIds": { "type": "array", "items": { "type": "integer" }, "description": "Filter sessions by roaming connection. Accepts one or more roaming connection IDs." } } }, "customFields": { "type": "string", "example": "filter[customFields.invoiceReference]=INV-42", "description": "Filter a custom-field host resource by custom fields defined for that resource. Add one literal `customFields.` key to the existing `filter` object for each criterion. The identifier suffix is administrator-defined and is never enumerated in this schema or generated per tenant. Use a scalar for boolean, text, email, and URL fields. Boolean accepts booleans and integer `1` or `0`, as well as the strings `\"true\"`, `\"false\"`, `\"1\"`, and `\"0\"`. Text, email, and URL accept strings and use contains matching that is case- and accent-insensitive; backslashes, `%`, and `_` are treated literally rather than as pattern syntax. Use `from`, `to`, or both below the dotted key for number, date, and date-time fields. Both bounds are inclusive. Number bounds are decimal strings from `-99999999999999.999999` through `99999999999999.999999` with at most six decimal places; comparisons preserve submitted and stored decimal precision without rounding. Date bounds use `YYYY-MM-DD` and compare calendar dates without time-zone conversion. Date-time bounds use ISO 8601; offsets are normalized to UTC, and an omitted offset is interpreted as UTC. Multiple identifiers combine with AND. Empty scalar criteria and ranges whose bounds are empty are ignored. An identifier resolves only to its current active definition, so values belonging to a deleted definition never match if its identifier is reused. Operator-scoped filters match only host records whose current operator owner is assigned to the field; retained inapplicable values are excluded before pagination. Unknown, inaccessible, tenant-disabled, resource-disabled, deleted, and otherwise unavailable identifiers all return the same non-disclosing `404` response. An active accessible custom field whose filtering is disabled returns `422` with `Custom field \"{identifier}\" is not filterable for resource \"{resource}\".` Malformed objects or values, a criterion shape that is invalid for the field type, and a range whose `from` bound is greater than its `to` bound return `422`. Custom-field filters apply only to resource listings. They do not participate in search and do not depend on an `include` parameter; any unrelated includes are defined by the host resource. Examples: `filter[customFields.invoiceReference]=INV-42` and `filter[customFields.capacity][from]=10&filter[customFields.capacity][to]=20`. URL-encode the query keys and values when sending the request." } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "include": { "description": "Include additional information in the response. The following options are available:
- `externalAppData`: Include external application data in the response", "schema": { "type": "array", "items": { "type": "string", "enum": [ "externalAppData" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The requested custom field filter identifier is unavailable" }, "422": { "description": "The request contains invalid criteria, including malformed or non-filterable custom field filters" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sessions/v1.0/{session}", "method": "GET", "operationId": "sessionRead", "summary": "Session / Read", "tags": [ "resource / sessions" ], "parameters": { "path": { "session": { "description": "The session ID to fetch", "type": "string", "required": true } }, "query": { "withClockAlignedEnergyConsumption": { "type": "boolean", "default": false }, "clockAlignedInterval": { "schema": { "type": "integer", "enum": [ 15, 30, 60 ], "default": 15 } }, "withAuthorization": { "type": "boolean", "default": false }, "withChargingPeriods": { "type": "boolean", "default": false }, "withChargingPeriodsPriceBreakdown": { "description": "Must be used in combination with `withChargingPeriods` parameter.", "type": "boolean", "default": false }, "withPriceBreakdown": { "type": "boolean", "default": false }, "withDurationBreakdown": { "description": "Return the charging and idle duration breakdown, including billable and grace-period seconds. Each session reports only the charging periods it owns. When an extending session is billed together with the session it extends, the grace period is consumed once along the combined timeline of both sessions, so the two responses can be summed without double counting.", "type": "boolean", "default": false }, "include": { "description": "Include additional information in the response. The following options are available:
- `externalAppData`: Include external application data in the response
- `chargingProfile`: Include the TX charging profile applied to the session in the response
- `vehicle`: Include the nested `vehicle` object describing the vehicle associated with the session
- `timelineSnapshot`: Include the pre-computed timeline snapshot for a finished session when available", "schema": { "type": "array", "items": { "type": "string", "enum": [ "externalAppData", "chargingProfile", "vehicle", "timelineSnapshot" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sessions/v1.0/{session}/consumption-stats", "method": "GET", "operationId": "sessionsConsumptionStatsRead", "summary": "Sessions / Consumption Stats / Read", "description": "Consumption statistics may differ between active and finished sessions, as finished sessions display aggregated final data with a maximum of 300 items.", "tags": [ "resource / sessions" ], "parameters": { "path": { "session": { "description": "The session ID to fetch", "type": "string", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sessions/v1.0/{session}/energy-coupon-session-consumptions", "method": "GET", "operationId": "energyCouponSessionConsumptionsListing", "summary": "Session / Energy coupon session consumptions", "description": "List the energy coupons consumed during a charging session, with the energy consumed from each.", "tags": [ "resource / sessions" ], "parameters": { "path": { "session": { "description": "The session ID to fetch", "type": "string", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sessions/v1.0/{session}/timeline-snapshot", "method": "GET", "operationId": "sessionTimelineSnapshotRead", "summary": "Sessions / Timeline Snapshot / Read", "description": "Returns the meter value time-series and lifecycle events for a finished charging session. **Availability.** Snapshots are generated when a session completes. Active sessions return 404. Finished sessions without snapshots, including sessions that finished before snapshot generation was available, also return 404. There is no historical backfill. Confirmed transaction boundary events are included only in snapshots generated after those event types became available; existing snapshots are not modified. A boundary event is omitted when its timestamp or precise meter reading is unavailable. **For active sessions**, use `GET /logs/communication/v1.0?filter[sessionId]={id}&filter[command]=MeterValues` to read real-time OCPP meter values from communication logs (6-month retention).", "tags": [ "resource / sessions" ], "parameters": { "path": { "session": { "description": "The session ID to fetch", "type": "string", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/settings/v1.0", "method": "GET", "operationId": "settingsListing", "summary": "Settings / Listing", "description": "Get all settings", "tags": [ "resource / settings" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sharing-invites/v1.0", "method": "GET", "operationId": "sharingInvitesListing", "summary": "Sharing invites / Listing", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Get all sharing invites. A sharing invite represents a personal charge point owner sharing their charge point with another user.", "tags": [ "resource / sharing invites" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "chargePointId": { "type": "integer" }, "userId": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sharing-invites/v1.0/{sharingInvite}", "method": "GET", "operationId": "sharingInviteRead", "summary": "Sharing invite / Read", "description": "⚠️ Experimental endpoint — not yet a stable contract. This resource ships as experimental / beta. While experimental, its schema and behaviour may change without a version bump — including breaking changes within v1.0 itself. Anyone consuming it does so for evaluation only, or by coordinating adoption with their account manager so changes can be sequenced with them. It graduates to a stable, version-locked contract (where the normal breaking-change rules apply) only when this experimental notice is removed. Get a single sharing invite.", "tags": [ "resource / sharing invites" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sub-operators/v1.0", "method": "GET", "operationId": "subOperatorsListingDeprecated", "summary": "Sub operators / Listing", "description": "**Deprecated.** Use v2.0 endpoint instead for enhanced functionality.", "deprecated": true, "tags": [ "resource / sub operators" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sub-operators/v1.0/{subOperator}", "method": "GET", "operationId": "subOperatorReadDeprecated", "summary": "Sub operator / Read", "description": "**Deprecated.** Use v2.0 endpoint instead for enhanced functionality.", "deprecated": true, "tags": [ "resource / sub operators" ], "parameters": { "path": { "subOperator": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sub-operators/v2.0", "method": "GET", "operationId": "subOperatorsListing", "summary": "Sub-operators / Listing", "description": "Get all sub-operators. Returns sub-operators ordered by their English (en) name ascending. The order is fixed and cannot be changed. Uses cursor-based pagination.", "tags": [ "resource / sub operators" ], "parameters": { "query": { "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "partnerId": { "type": "integer", "description": "Filter by associated partner ID" }, "hasStripeAccount": { "type": "boolean", "description": "Filter by Stripe Connect account presence" }, "directPaymentEnabled": { "type": "boolean", "description": "Filter by direct payment capability" }, "country": { "type": "string", "description": "Filter by ISO 3166-1 alpha-2 country code (exact match)" }, "state": { "type": "string", "description": "Filter by state/province code for countries with predefined states (US, CA, AU, UM, RO) (exact match)" }, "name": { "type": "string", "description": "Filter by sub-operator name (partial match against the English (en) name only)" }, "businessName": { "type": "string", "description": "Filter by business name (partial match)" }, "region": { "type": "string", "description": "Filter by region for countries without predefined states (partial match against the English (en) region only)" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "Filter by records updated after this ISO 8601 datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "Filter by records updated before this ISO 8601 datetime" }, "externalId": { "type": "string", "description": "Filter by external identifier (exact match)" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sub-operators/v2.0", "method": "POST", "operationId": "subOperatorCreate", "summary": "Sub-operators / Create", "description": "Create a new sub-operator", "tags": [ "resource / sub operators" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "businessName": { "type": "string", "maxLength": 255, "description": "Official business name for legal/financial purposes" }, "externalId": { "type": "string", "maxLength": 255, "description": "External system identifier for integration purposes" }, "regNo": { "type": "string", "maxLength": 255, "description": "Company registration number" }, "taxNo": { "type": "string", "maxLength": 255, "description": "Tax identification number" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "description": "ISO 3166-1 alpha-2 country code" }, "state": { "anyOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "When the country is US." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "When the country is AU." }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" ], "description": "When the country is CA." }, { "type": "string", "enum": [ "81", "84", "85", "67", "89", "71", "76", "95", "79" ], "description": "When the country is UM." }, { "type": "string", "enum": [ "AB", "AR", "AG", "BC", "BH", "BN", "BT", "BV", "BR", "B", "BZ", "CL", "CS", "CT", "CV", "DB", "DJ", "GL", "GR", "GJ", "HR", "HD", "IL", "IS", "IF", "MM", "MH", "MS", "NT", "OT", "PH", "SM", "SJ", "SB", "SV", "TR", "TM", "TL", "VS", "VL", "VN" ], "description": "When the country is RO." } ], "description": "When the selected country is one of US, AU, CA, UM or RO" }, "postcode": { "type": "string", "maxLength": 255, "description": "Postal/ZIP code" }, "contactPerson": { "type": "string", "maxLength": 255, "description": "Primary contact person name" }, "phone": { "type": "string", "maxLength": 255, "description": "Contact phone number" }, "email": { "type": "string", "maxLength": 255, "description": "Contact email address" }, "faultNotificationsEmail": { "type": "string", "format": "email", "maxLength": 255, "description": "Email address for receiving fault notifications" }, "businessOperationalContext": { "type": "string", "description": "Long-form business context and operational notes" }, "capabilities": { "type": "object", "properties": { "canControlChargePoints": { "type": "boolean", "default": false, "description": "Whether the sub-operator can control charge points" }, "canControlTariff": { "type": "boolean", "default": false, "description": "Whether the sub-operator can control tariffs" }, "canControlTariffGroups": { "type": "boolean", "default": false, "description": "Whether the sub-operator can control tariff groups" }, "canControlPartnersTariffsAndTariffGroups": { "type": "boolean", "default": false, "description": "Whether the sub-operator can control partners' tariffs and tariff groups" } } }, "partnerIds": { "type": "array", "items": { "type": "integer" }, "description": "List of associated partner IDs" }, "translatedName": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string", "maxLength": 255 } }, "required": [ "locale", "translation" ] }, "minItems": 1, "description": "Display name of the sub-operator per locale. Whenever this field is submitted — on both create and update — the array must contain an `en` entry. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the name: locales absent from the array are cleared. Omit the field to leave every existing locale untouched. An empty array is rejected on both create and update — the name cannot be cleared. Cannot be provided together with the deprecated `name`." }, "translatedAddress": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string", "maxLength": 255 } }, "required": [ "locale", "translation" ] }, "description": "Street address of the sub-operator per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the address: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `address`." }, "translatedCity": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string", "maxLength": 255 } }, "required": [ "locale", "translation" ] }, "description": "City of the sub-operator per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the city: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `city`." }, "translatedRegion": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string", "maxLength": 255 } }, "required": [ "locale", "translation" ] }, "description": "Region of the sub-operator per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the region: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Rejected when the sub-operator's country supports states (US, CA, AU, UM, RO) — `state` applies instead and is not translatable. Cannot be provided together with the deprecated `region`." }, "name": { "type": "string", "maxLength": 255, "description": "**This property is deprecated. Use `translatedName` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedName`. Display name of the sub-operator." }, "city": { "type": "string", "maxLength": 255, "description": "**This property is deprecated. Use `translatedCity` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedCity`. City name" }, "region": { "type": "string", "nullable": true, "description": "When country is not in US, AU, CA, UM or RO, you can provide the region" }, "address": { "type": "string", "maxLength": 255, "description": "**This property is deprecated. Use `translatedAddress` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedAddress`. Street address" } }, "required": [ "businessName" ], "description": "At least one of `name` or `translatedName` must be provided. Supplying both is rejected with a `422` response. When `translatedName` is used it must carry an `en` entry. A deprecated field and its `translated` sibling are mutually exclusive: `name`/`translatedName`, `address`/`translatedAddress`, `city`/`translatedCity` and `region`/`translatedRegion` may each be sent one at a time, never both." } } } }, "responses": { "201": { "description": "Sub-operator created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sub-operators/v2.0/{subOperator}", "method": "GET", "operationId": "subOperatorRead", "summary": "Sub-operators / Read", "description": "Get a single sub-operator", "tags": [ "resource / sub operators" ], "parameters": { "query": { "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "stripeConnect" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sub-operators/v2.0/{subOperator}", "method": "DELETE", "operationId": "subOperatorDelete", "summary": "Sub-operators / Delete", "description": "Permanently delete a sub-operator. When deleted, associated partners are unassociated but remain intact. All admin accounts belonging to this sub-operator are also deleted.", "tags": [ "resource / sub operators" ], "responses": { "204": { "description": "Sub-operator deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sub-operators/v2.0/{subOperator}", "method": "PATCH", "operationId": "subOperatorUpdate", "summary": "Sub-operators / Update", "description": "Update an existing sub-operator. Only provided fields are updated - omitted fields retain their current values. Send null for nullable fields to explicitly clear their values.", "tags": [ "resource / sub operators" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "translatedName": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string", "maxLength": 255 } }, "required": [ "locale", "translation" ] }, "minItems": 1, "description": "Display name of the sub-operator per locale. Whenever this field is submitted — on both create and update — the array must contain an `en` entry. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the name: locales absent from the array are cleared. Omit the field to leave every existing locale untouched. An empty array is rejected on both create and update — the name cannot be cleared. Cannot be provided together with the deprecated `name`." }, "translatedAddress": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string", "maxLength": 255 } }, "required": [ "locale", "translation" ] }, "description": "Street address of the sub-operator per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the address: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `address`." }, "translatedCity": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string", "maxLength": 255 } }, "required": [ "locale", "translation" ] }, "description": "City of the sub-operator per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the city: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Cannot be provided together with the deprecated `city`." }, "translatedRegion": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale configured for the tenant" }, "translation": { "type": "string", "maxLength": 255 } }, "required": [ "locale", "translation" ] }, "description": "Region of the sub-operator per locale. Only locales configured for the tenant are accepted. Submitting this field replaces the whole locale set for the region: locales absent from the array are cleared. Omit the field to leave every existing locale untouched; submit an empty array to clear them all. Rejected when the sub-operator's country supports states (US, CA, AU, UM, RO) — `state` applies instead and is not translatable. Cannot be provided together with the deprecated `region`." }, "name": { "type": "string", "maxLength": 255, "description": "**This property is deprecated. Use `translatedName` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedName`. Display name of the sub-operator." }, "businessName": { "type": "string", "maxLength": 255, "description": "Official business name for legal/financial purposes" }, "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "External system identifier. Send null to clear." }, "regNo": { "type": "string", "maxLength": 255, "nullable": true, "description": "Company registration number. Send null to clear." }, "taxNo": { "type": "string", "maxLength": 255, "nullable": true, "description": "Tax identification number. Send null to clear." }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW", null ], "nullable": true, "description": "ISO 3166-1 alpha-2 country code. Send null to clear." }, "city": { "type": "string", "maxLength": 255, "nullable": true, "description": "**This property is deprecated. Use `translatedCity` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedCity`. City name. Send null to clear the English (`en`) value only — every other locale is left untouched. Use `translatedCity` to clear other locales." }, "state": { "anyOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "When the country is US." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "When the country is AU." }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" ], "description": "When the country is CA." }, { "type": "string", "enum": [ "81", "84", "85", "67", "89", "71", "76", "95", "79" ], "description": "When the country is UM." }, { "type": "string", "enum": [ "AB", "AR", "AG", "BC", "BH", "BN", "BT", "BV", "BR", "B", "BZ", "CL", "CS", "CT", "CV", "DB", "DJ", "GL", "GR", "GJ", "HR", "HD", "IL", "IS", "IF", "MM", "MH", "MS", "NT", "OT", "PH", "SM", "SJ", "SB", "SV", "TR", "TM", "TL", "VS", "VL", "VN" ], "description": "When the country is RO." } ], "description": "When the selected country is one of US, AU, CA, UM or RO" }, "region": { "type": "string", "nullable": true, "description": "When country is not in US, AU, CA, UM or RO, you can provide the region" }, "postcode": { "type": "string", "maxLength": 255, "nullable": true, "description": "Postal/ZIP code. Send null to clear." }, "address": { "type": "string", "maxLength": 255, "nullable": true, "description": "**This property is deprecated. Use `translatedAddress` instead.** The value is written to the English (`en`) locale only. Cannot be provided together with `translatedAddress`. Street address. Send null to clear the English (`en`) value only — every other locale is left untouched. Use `translatedAddress` to clear other locales." }, "contactPerson": { "type": "string", "maxLength": 255, "nullable": true, "description": "Primary contact person name. Send null to clear." }, "phone": { "type": "string", "maxLength": 255, "nullable": true, "description": "Contact phone number. Send null to clear." }, "email": { "type": "string", "maxLength": 255, "nullable": true, "description": "Contact email address. Send null to clear." }, "faultNotificationsEmail": { "type": "string", "format": "email", "maxLength": 255, "nullable": true, "description": "Email address for receiving fault notifications. Must be a valid email format. Send null to clear." }, "businessOperationalContext": { "type": "string", "nullable": true, "description": "Long-form business context and operational notes. Send null to clear." }, "capabilities": { "type": "object", "properties": { "canControlChargePoints": { "type": "boolean", "default": false, "description": "Whether the sub-operator can control charge points" }, "canControlTariff": { "type": "boolean", "default": false, "description": "Whether the sub-operator can control tariffs" }, "canControlTariffGroups": { "type": "boolean", "default": false, "description": "Whether the sub-operator can control tariff groups" }, "canControlPartnersTariffsAndTariffGroups": { "type": "boolean", "default": false, "description": "Whether the sub-operator can control partners' tariffs and tariff groups" } } }, "partnerIds": { "type": "array", "items": { "type": "integer" }, "description": "List of partner IDs to associate. Replaces existing associations." } }, "description": "A deprecated field and its `translated` sibling are mutually exclusive: `name`/`translatedName`, `address`/`translatedAddress`, `city`/`translatedCity` and `region`/`translatedRegion` may each be sent one at a time, never both. Supplying both is rejected with a `422` response." } } } }, "responses": { "200": { "description": "Sub-operator updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sub-operators/v2.0/{subOperator}/notes", "method": "GET", "operationId": "subOperatorNotesListing", "summary": "Sub Operator / Notes / Listing", "description": "List all notes for a specific sub-operator. Notes are returned with pinned notes first, then ordered by creation date descending. **Required permission:** `Notes.view`", "tags": [ "resource / sub operators" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "pinned": { "type": "boolean", "example": true, "description": "Filter by pinned status" }, "createdAfter": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z", "description": "Filter notes created on or after this ISO-8601 datetime" }, "createdBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes created on or before this ISO-8601 datetime" }, "updatedAfter": { "type": "string", "format": "date-time", "example": "2025-12-01T00:00:00Z", "description": "Filter notes updated on or after this ISO-8601 datetime (useful for delta sync)" }, "updatedBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes updated on or before this ISO-8601 datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sub-operators/v2.0/{subOperator}/notes", "method": "POST", "operationId": "subOperatorNoteCreate", "summary": "Sub Operator / Note / Create", "description": "Create a new note for a specific sub-operator. **Required permission:** `Notes.create`", "tags": [ "resource / sub operators" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Important maintenance note", "description": "Short summary or title of the note (required)" }, "details": { "type": "string", "maxLength": 2000, "example": "This charge point requires monthly inspection due to high usage.", "description": "Detailed content of the note (optional)" }, "pinned": { "type": "boolean", "default": false, "example": false, "description": "Whether the note should be pinned (optional, defaults to false)" } }, "required": [ "summary" ] } } } }, "responses": { "201": { "description": "Note created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sub-operators/v2.0/{subOperator}/notes/{note}", "method": "GET", "operationId": "subOperatorNoteShow", "summary": "Sub Operator / Note / Read", "description": "Get a specific note for a sub-operator. **Required permission:** `Notes.view`", "tags": [ "resource / sub operators" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sub-operators/v2.0/{subOperator}/notes/{note}", "method": "DELETE", "operationId": "subOperatorNoteDelete", "summary": "Sub Operator / Note / Delete", "description": "Delete a specific note from a sub-operator. Notes are permanently deleted (hard delete). **Required permission:** `Notes.delete`", "tags": [ "resource / sub operators" ], "responses": { "204": { "description": "Note deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/sub-operators/v2.0/{subOperator}/notes/{note}", "method": "PATCH", "operationId": "subOperatorNoteUpdate", "summary": "Sub Operator / Note / Update", "description": "Update a specific note for a sub-operator. **Required permissions:** - `Notes.update` for updating summary and details - `Notes.pin` for updating the pinned field (in addition to Notes.update if other fields are included)", "tags": [ "resource / sub operators" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Updated maintenance note", "description": "Short summary or title of the note" }, "details": { "type": "string", "maxLength": 2000, "example": "Updated inspection schedule.", "nullable": true, "description": "Detailed content of the note. Send null to clear." }, "pinned": { "type": "boolean", "example": true, "description": "Whether the note should be pinned. Requires Notes.pin permission." } } } } } }, "responses": { "200": { "description": "Note updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/subscription-plans/v1.0", "method": "GET", "operationId": "subscriptionPlansListingDeprecated", "summary": "Subscription Plans / Listing", "description": "Get all Subscription Plans", "deprecated": true, "tags": [ "resource / subscription-plans" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/subscription-plans/v2.0", "method": "GET", "operationId": "subscriptionPlansListing", "summary": "Subscription plans / Listing", "description": "Get all Subscription plans", "tags": [ "resource / subscription-plans" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the subscription plans that were created on and after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the subscription plans that were created on and before this datetime" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the subscription plans that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the subscription plans that were last updated on and before this datetime" }, "externalId": { "type": "string", "description": "Lists subscription plans whose external ID matches exactly" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "405": { "description": "Feature disabled for the system" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/subscription-plans/v2.0", "method": "POST", "operationId": "subscriptionPlanCreate", "summary": "Subscription plan / Create", "description": "Create a new Subscription plans", "tags": [ "resource / subscription-plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "name": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "description": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "renewalCycle": { "type": "string", "enum": [ "monthly", "annually" ] }, "freeRenewalPeriods": { "type": "integer", "nullable": true, "description": "The number of renewal periods that are free of charge. This is only applicable for pre-paid plans." }, "type": { "type": "string", "enum": [ "pre-paid", "post-paid" ] }, "baseFee": { "type": "number", "format": "float", "nullable": true, "description": "For pre-paid plans this is the price, for post-paid plans this is the base fee." }, "baseFeeAppliesPerEachHomeCharger": { "type": "boolean", "default": false, "nullable": true, "description": "Deprecated: Use feePerEachPersonalChargePoint instead." }, "feePerEachPersonalChargePoint": { "type": "number", "format": "float", "nullable": true, "description": "Applies separately per each personal charge point owned by the subscriber that requires this Subscription plan. These fees are added to the Base fee of the Subscription plan, if any." }, "postPaidChargingSessionsAccumulation": { "type": "string", "enum": [ "none", "personal", "personal_commercial" ], "default": "none", "description": "Indicates if charging sessions at personal, commercial+personal charge points are included in the post-paid subscription and would be billed at the end of the billing cycle or when a threshold is met, if there is such." }, "billingUsageThreshold": { "type": "integer", "format": "decimal", "nullable": true, "description": "If this threshold is reached, the amount due for the subscription would be billed immediately instead of waiting for the end of the billing period." }, "billingType": { "type": "string", "enum": [ "default", "internal", "external" ], "description": "Applicable only for post-paid subscription plans when external billing is enabled. Controls the billing method used for this subscription plan." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "allowance": { "type": "object", "properties": { "resetCycle": { "type": "string", "enum": [ "as_renewal_cycle", "after_each_session", "after_24_hours", "after_each_week", "after_each_month", "after_each_year" ] }, "type": { "type": "string", "enum": [ "none", "combined", "separate" ] }, "homeChargersOnly": { "type": "boolean", "default": false, "description": "When true the allowance can only be used on the home charge points owned by the user. In that case all other allowance restrictions have no effect ." }, "includedCountries": { "type": "array", "items": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "description": "The allowance can only be used on charge points in countries in this list. When empty the allowance is valid for charge points in all countries, except the ones explicitly listed in the excludedCountries." }, "excludedCountries": { "type": "array", "items": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "description": "The allowance cannot be used on charge points in the countries in this list." }, "excludeRoaming": { "type": "boolean", "default": false, "description": "When true the allowance cannot be used on roaming charge points." }, "includedPartnerChargePoints": { "type": "array", "items": { "type": "integer" }, "description": "An array of Partner IDs. The allowance can only be used on charge points of Partners in this list. When empty the allowance is valid for charge points of any Partner, except the ones explicitly listed in the excludedPartnerChargePoints." }, "excludedPartnerChargePoints": { "type": "array", "items": { "type": "integer" }, "description": "An array of Partner IDs. The allowance cannot be used on charge points of Partners in this list." }, "combined": { "type": "integer", "minimum": 0, "maximum": 4000000, "nullable": true, "description": "The amount of kWh included - combined for AC and DC, should be provided if the type is combined." }, "ac": { "type": "integer", "minimum": 0, "maximum": 4000000, "nullable": true, "description": "The amount of kWh included for AC, should be provided if the type is separate." }, "dc": { "type": "integer", "minimum": 0, "maximum": 4000000, "nullable": true, "description": "The amount of kWh included for DC, should be provided if the type is separate." } } }, "visibilityRestrictions": { "type": "object", "properties": { "includedPartnerUsers": { "type": "array", "items": { "type": "integer" }, "description": "An array of Partner IDs. The Subscription plan is available only to users invited (and accepted) or created by one of the Partners in this list. When empty the plan is available to all users, except the ones of Partners listed in excludedPartnerUsers." }, "excludedPartnerUsers": { "type": "array", "items": { "type": "integer" }, "description": "An array of Partner IDs. The Subscription plan is not available to users of the Partners in this list." }, "includedUserGroups": { "type": "array", "items": { "type": "integer" }, "description": "An array of User Group IDs. The Subscription plan is available only to users with a User Group that is in this list. When empty the plan is available to all users, except the ones with a User Group listed in excludedUserGroups." }, "excludedUserGroups": { "type": "array", "items": { "type": "integer" }, "description": "An array of User Group IDs. The Subscription plan is not available to users with a User Group that is in this list." } }, "description": "Defines which users can view and subscribe to the plan via the app" }, "externalId": { "type": "string", "maxLength": 255, "description": "An optional external identifier for integration purposes" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "name", "description", "renewalCycle", "type", "status" ] } } } }, "responses": { "201": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/subscription-plans/v2.0/{subscriptionPlan}", "method": "GET", "operationId": "subscriptionPlanRead", "summary": "Subscription plan / Read", "description": "Get a single subscription plan", "tags": [ "resource / subscription-plans" ], "parameters": { "path": { "subscriptionPlan": { "description": "The ID of the subscription plan", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/subscription-plans/v2.0/{subscriptionPlan}", "method": "DELETE", "operationId": "subscriptionPlanDelete", "summary": "Subscription plan / Delete", "description": "Delete a Subscription plan", "tags": [ "resource / subscription-plans" ], "parameters": { "path": { "subscriptionPlan": { "description": "The ID of the subscription plan", "type": "integer", "required": true } } }, "responses": { "204": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/subscription-plans/v2.0/{subscriptionPlan}", "method": "PATCH", "operationId": "subscriptionPlanUpdate", "summary": "Subscription plan / Update", "description": "Update a Subscription plan", "tags": [ "resource / subscription-plans" ], "parameters": { "path": { "subscriptionPlan": { "description": "The ID of the subscription plan", "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "description": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "renewalCycle": { "type": "string", "enum": [ "monthly", "annually" ] }, "freeRenewalPeriods": { "type": "integer", "nullable": true, "description": "The number of renewal periods that are free of charge. This is only applicable for pre-paid plans." }, "type": { "type": "string", "enum": [ "pre-paid", "post-paid" ], "description": "Required when Post-paid Subscription plans has been enabled for the system." }, "baseFee": { "type": "number", "format": "float", "nullable": true, "description": "For pre-paid plans this is the price, for post-paid plans this is the base fee." }, "feePerEachPersonalChargePoint": { "type": "number", "format": "float", "nullable": true, "description": "Applies separately per each personal charge point owned by the subscriber that requires this Subscription plan. These fees are added to the Base fee of the Subscription plan, if any." }, "postPaidChargingSessionsAccumulation": { "type": "string", "enum": [ "none", "personal", "personal_commercial" ], "default": "none", "description": "Indicates if charging sessions at personal, commercial+personal charge points are included in the post-paid subscription and would be billed at the end of the billing cycle or when a threshold is met, if there is such." }, "billingUsageThreshold": { "type": "integer", "format": "decimal", "nullable": true, "description": "If this threshold is reached, the amount due for the subscription would be billed immediately instead of waiting for the end of the billing period." }, "billingType": { "type": "string", "enum": [ "default", "internal", "external" ], "description": "Applicable only for post-paid subscription plans when external billing is enabled. Controls the billing method used for this subscription plan." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "A change from disabled to enabled is only possible for Subscription plans that are not replaced with another plan." }, "allowance": { "type": "object", "properties": { "resetCycle": { "type": "string", "enum": [ "as_renewal_cycle", "after_each_session", "after_24_hours", "after_each_week", "after_each_month", "after_each_year" ] }, "type": { "type": "string", "enum": [ "none", "combined", "separate" ] }, "homeChargersOnly": { "type": "boolean", "default": false, "description": "When true the allowance can only be used on the home charge points owned by the user. In that case all other allowance restrictions have no effect ." }, "includedCountries": { "type": "array", "items": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "description": "The allowance can only be used on charge points in countries in this list. When empty the allowance is valid for charge points in all countries, except the ones explicitly listed in the excludedCountries." }, "excludedCountries": { "type": "array", "items": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "description": "The allowance cannot be used on charge points in the countries in this list." }, "excludeRoaming": { "type": "boolean", "default": false, "description": "When true the allowance cannot be used on roaming charge points." }, "includedPartnerChargePoints": { "type": "array", "items": { "type": "integer" }, "description": "An array of Partner IDs. The allowance can only be used on charge points of Partners in this list. When empty the allowance is valid for charge points of any Partner, except the ones explicitly listed in the excludedPartnerChargePoints." }, "excludedPartnerChargePoints": { "type": "array", "items": { "type": "integer" }, "description": "An array of Partner IDs. The allowance cannot be used on charge points of Partners in this list." }, "combined": { "type": "integer", "minimum": 0, "maximum": 4000000, "nullable": true, "description": "The amount of kWh included - combined for AC and DC, should be provided if the type is combined." }, "ac": { "type": "integer", "minimum": 0, "maximum": 4000000, "nullable": true, "description": "The amount of kWh included for AC, should be provided if the type is separate." }, "dc": { "type": "integer", "minimum": 0, "maximum": 4000000, "nullable": true, "description": "The amount of kWh included for DC, should be provided if the type is separate." } } }, "visibilityRestrictions": { "type": "object", "properties": { "includedPartnerUsers": { "type": "array", "items": { "type": "integer" }, "description": "An array of Partner IDs. The Subscription plan is available only to users invited (and accepted) or created by one of the Partners in this list. When empty the plan is available to all users, except the ones of Partners listed in excludedPartnerUsers." }, "excludedPartnerUsers": { "type": "array", "items": { "type": "integer" }, "description": "An array of Partner IDs. The Subscription plan is not available to users of the Partners in this list." }, "includedUserGroups": { "type": "array", "items": { "type": "integer" }, "description": "An array of User Group IDs. The Subscription plan is available only to users with a User Group that is in this list. When empty the plan is available to all users, except the ones with a User Group listed in excludedUserGroups." }, "excludedUserGroups": { "type": "array", "items": { "type": "integer" }, "description": "An array of User Group IDs. The Subscription plan is not available to users with a User Group that is in this list." } }, "description": "Defines which users can view and subscribe to the plan via the app" }, "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "An optional external identifier for integration purposes" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } } } ] } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/subscriptions/v1.0", "method": "GET", "operationId": "subscriptionsListing", "summary": "Subscriptions / Listing", "description": "Get all subscriptions", "tags": [ "resource / subscriptions" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "planId": { "type": "string", "format": "number" }, "startedAfter": { "type": "string", "format": "date-time", "description": "Filter subscriptions started on or after this ISO 8601 formatted datetime" }, "startedBefore": { "type": "string", "format": "date-time", "description": "Filter subscriptions started on or before this ISO 8601 formatted datetime" }, "endedAfter": { "type": "string", "format": "date-time", "description": "Filter subscriptions ended on or after this ISO 8601 formatted datetime" }, "endedBefore": { "type": "string", "format": "date-time", "description": "Filter subscriptions ended on or before this ISO 8601 formatted datetime" }, "endDateFrom": { "type": "string", "format": "date-time", "description": "Filter subscriptions ended on or after this ISO 8601 formatted datetime" }, "endDateTo": { "type": "string", "format": "date-time", "description": "Filter subscriptions ended on or before this ISO 8601 formatted datetime" }, "status": { "type": "string", "enum": [ "active", "canceled", "expired", "suspended", "pending" ] }, "statusChangedAfter": { "type": "string", "format": "date-time", "description": "Filter subscriptions with status changed on or after this ISO 8601 formatted datetime. Requires the status filter to be provided." }, "statusChangedBefore": { "type": "string", "format": "date-time", "description": "Filter subscriptions with status changed on or before this ISO 8601 formatted datetime. Requires the status filter to be provided." }, "billedExternally": { "type": "string", "format": "boolean", "description": "Applicable only when the system uses both payment processor and external billing mode simultaneously. Show or hide subscriptions where users have enabled \"External billing\" (if allowed by the Billing settings)." } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "405": { "description": "Feature disabled for the system" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/subscriptions/v1.0/{subscription}", "method": "GET", "operationId": "subscriptionRead", "summary": "Subscription / Read", "description": "Get a single subscription", "tags": [ "resource / subscriptions" ], "parameters": { "path": { "subscription": { "description": "The subscription ID", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "405": { "description": "Feature disabled for the system" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariff-groups/v1.0", "method": "GET", "operationId": "tariffGroupsListing", "summary": "Tariff Groups / Listing", "description": "Get all tariff groups", "tags": [ "resource / tariffs" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "partnerId": { "type": "number", "description": "Only list tariff groups managed by certain partner." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the tariff groups that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the tariff groups that were last updated on and before this datetime" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the tariff groups that were created on and after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the tariff groups that were created on and before this datetime" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariff-groups/v1.0", "method": "POST", "operationId": "tariffGroupCreate", "summary": "Tariff Group / Create", "description": "Create new tariff group. When the tariff group is created a base tariff is also created. The type of the base tariff (free or charging not allowed) is determined by the respective setting of the operator.", "tags": [ "resource / tariffs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "display": { "type": "object", "properties": { "defaultPriceInformation": { "type": "string", "maxLength": 150, "nullable": true, "description": "The default information that would be shown on the display of the charge point without the user having authorized themselves." }, "defaultPriceInformationOffline": { "type": "string", "maxLength": 150, "nullable": true, "description": "The information that would be shown on the display of the charge point when offline. For OCPP 2.0.1 charge points that support tariff and cost display, this value is also set as the `TariffCostCtrlr.TariffFallbackMessage` variable." }, "totalCostFallbackMessage": { "type": "string", "maxLength": 150, "description": "The message shown on the charge point screen when a session ends but the final cost cannot be retrieved. For OCPP 2.0.1 charge points that support tariff and cost display, this value is set as the `TariffCostCtrlr.TotalCostFallbackMessage` variable." } } }, "name": { "type": "string" }, "tariffIds": { "type": "array", "items": { "type": "integer" }, "description": "Ordered list of tariff ids in the group. The first element is always the base tariff, which is auto-created with the group. Please note that the order is checked from bottom to top, meaning that the tariff with the largest index in that list (in other words that is the lowest in the list), that matches the requirements will apply" }, "partnerId": { "type": "integer", "nullable": true, "description": "The assigned Partner will have access to make changes to the tariff group." }, "offlineTariffId": { "type": "integer", "nullable": true, "description": "The tariff used to derive offline pricing for OCPP 1.6 charge points when they are not connected to the backend. Must belong to the same operator as the tariff group. Set to null to clear the assignment." }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Tariff group created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariff-groups/v1.0/{tariffGroup}", "method": "GET", "operationId": "tariffGroupRead", "summary": "Tariff Group / Read", "description": "Get a tariff group", "tags": [ "resource / tariffs" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariff-groups/v1.0/{tariffGroup}", "method": "PUT", "operationId": "tariffGroupUpdate", "summary": "Tariff Group / Update", "description": "Update a tariff group", "tags": [ "resource / tariffs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display": { "type": "object", "properties": { "defaultPriceInformation": { "type": "string", "maxLength": 150, "nullable": true, "description": "The default information that would be shown on the display of the charge point without the user having authorized themselves." }, "defaultPriceInformationOffline": { "type": "string", "maxLength": 150, "nullable": true, "description": "The information that would be shown on the display of the charge point when offline. For OCPP 2.0.1 charge points that support tariff and cost display, this value is also set as the `TariffCostCtrlr.TariffFallbackMessage` variable." }, "totalCostFallbackMessage": { "type": "string", "maxLength": 150, "nullable": true, "description": "The message shown on the charge point screen when a session ends but the final cost cannot be retrieved. For OCPP 2.0.1 charge points that support tariff and cost display, this value is set as the `TariffCostCtrlr.TotalCostFallbackMessage` variable. Set to null to clear the message." } } }, "name": { "type": "string" }, "tariffIds": { "type": "array", "items": { "type": "integer" }, "description": "Ordered list of tariff ids in the group. The first element is always the base tariff, which is auto-created with the group. Please note that the order is checked from bottom to top, meaning that the tariff with the largest index in that list (in other words that is the lowest in the list), that matches the requirements will apply" }, "partnerId": { "type": "integer", "nullable": true, "description": "The assigned Partner will have access to make changes to the tariff group." }, "offlineTariffId": { "type": "integer", "nullable": true, "description": "The tariff used to derive offline pricing for OCPP 1.6 charge points when they are not connected to the backend. Must belong to the same operator as the tariff group. Set to null to clear the assignment." }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariff-groups/v1.0/{tariffGroup}", "method": "DELETE", "operationId": "tariffGroupDelete", "summary": "Tariff Group / Delete", "description": "Delete a tariff group. **Deletion limitations** A tariff group cannot be deleted when either of the following is true: - Charge points are assigned to it — at least one EVSE currently references the tariff group. - It is the operator's default tariff group — the tariff group is marked as the default for the operator. Both conditions must be false for the deletion to succeed.", "tags": [ "resource / tariffs" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariff-snapshots/v1.0/{tariffSnapshot}", "method": "GET", "operationId": "tariffSnapshotRead", "summary": "Tariff Snapshot / Read", "description": "Get a tariff snapshot by id", "tags": [ "resource / tariffs" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariffs/v1.0", "method": "GET", "operationId": "tariffsListing", "summary": "Tariffs / Listing", "description": "Get all tariff. Also you could use the `tariffGroupId` and the `userId` to \"resolve\" the concrete tariff within a group that would be applied to the specified user.", "tags": [ "resource / tariffs" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "tariffGroupId": { "type": "string", "format": "integer", "description": "Only list tariffs in a certain group" }, "userId": { "type": "string", "format": "integer", "description": "Can only be used with `tariffGroupId`. When set, a single tariff of the group will be returned (no meta or link props will be included), that will be applied to the when the given user is charging. Note that when you set it to empty (null) then the tariff for anonymous charging will be returned" }, "type": { "type": "string", "description": "Only list tariff of this specific type" }, "partnerId": { "type": "string", "format": "integer", "description": "Only list tariffs managed by certain partner." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the tariffs that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the tariffs that were last updated on and before this datetime" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariffs/v1.0", "method": "POST", "operationId": "tariffCreate", "summary": "Tariff / Create", "description": "Create new tariff", "tags": [ "resource / tariffs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "name": { "type": "string" }, "description": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "additionalInformation": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "learnMoreUrl": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "dayTariffStart": { "type": "string", "format": "time", "description": "A time when the day begins" }, "nightTariffStart": { "type": "string", "format": "time", "description": "A time when the night begins" }, "pricing": { "type": "object", "properties": { "pricePerSession": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per session. Only applicable with flat rate tariffs. Up to 5 digits after the decimal point depending on the currency precision." }, "connectionFee": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection fee. A fixed fee that is applied at the start of the charging session. Up to 5 digits after the decimal point depending on the currency precision." }, "pricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh. Up to 5 digits after the decimal point depending on the currency precision." }, "dayPricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision." }, "nightPricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision." }, "pricePeriodInMinutes": { "type": "integer", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Charging period. In minutes. It defines the time-period for charging a fee. Example: If you select 15min then the EV-driver will be charged at the start of every 15min of EV-charging. Applicable for duration+energy and duration+energy time of day" }, "pricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period. Applicable for duration+energy. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`idleFeePerMinute`), the regular duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "durationFeeLimit": { "type": "number", "format": "decimal", "nullable": true, "description": "Duration fee limit for the whole session if fee is applied." }, "durationFeeCapMinutes": { "type": "integer", "nullable": true, "description": "Maximum billable charging duration in minutes. A value of zero means no duration fee is charged. Mutually exclusive with durationFeeLimit." }, "dayPricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`dayIdleFeePerMinute`), the regular day duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "nightPricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`nightIdleFeePerMinute`), the regular night duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "dayIdleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. When configured, this fee applies during idle periods (when no charging is occurring) and replaces the regular day duration fee (`dayPricePerPeriod`). If not configured, the regular day duration fee continues to apply during idle periods." }, "nightIdleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. When configured, this fee applies during idle periods (when no charging is occurring) and replaces the regular night duration fee (`nightPricePerPeriod`). If not configured, the regular night duration fee continues to apply during idle periods." }, "idleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging). Up to 5 digits after the decimal point depending on the currency precision. **For duration+energy tariffs:** When configured, this fee applies during idle periods and replaces the regular duration fee (`pricePerPeriod`). If not configured, the regular duration fee continues to apply during idle periods." }, "idleFeeGracePeriodMinutes": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee grace period (min). Optional. The interpretation of this field depends on `idleFeeGracePeriodMode`: - When mode is `idle_detection` (default): The user is given this grace period after idle state is detected (no charging) to remove the vehicle, before idle fee starts applying. - When mode is `session_start`: This represents the minimum session duration before idle fee applies. Idle fee will not be charged until the session has been active for at least this many minutes." }, "idleFeeGracePeriodMode": { "type": "string", "enum": [ "idle_detection", "session_start" ], "description": "Determines when the idle fee grace period timer starts counting. - `idle_detection` (default): Grace period begins when idle state is detected (vehicle stops charging but remains connected). - `session_start`: Grace period begins from session start time. Idle fee will not apply until the session has been active for at least the grace period duration. Applicable tariff types: `duration+energy`, `duration+energy time of day`, `energy tou`, `standard_tod`." }, "idlePricingPeriodInMinutes": { "type": "number", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging)." }, "idleFeePeriodStart": { "type": "string", "format": "time", "nullable": true, "description": "Defined start time for the application of idle fee." }, "idleFeePeriodEnd": { "type": "string", "format": "time", "nullable": true, "description": "Defined end time for the application of idle fee." }, "idleFeeLimit": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee limit for the whole session if fee is applied." }, "idleFeeCapMinutes": { "type": "integer", "nullable": true, "description": "Maximum billable idle time in minutes. A value of zero means no idle fee is charged. Mutually exclusive with idleFeeLimit." }, "connectionFeeMinimumSessionDuration": { "type": "integer", "nullable": true, "description": "Connection Fee Minimum Session Duration (min). Optional." }, "connectionFeeMinimumSessionEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection Fee Minimum Session Energy (kWh). Optional. Up to 5 digits after the decimal point depending on the currency precision." }, "durationFeeGracePeriod": { "type": "integer", "nullable": true, "description": "Duration Fee Grace Period (min). Optional." }, "minPrice": { "type": "number", "format": "decimal", "nullable": true, "description": "Min. price. Sets a minimum total amount per session. This is helpful in the case your payment service provider has a minimum transaction size or high transaction fees and you want to make sure to have a positive ROI per transaction. Up to 5 digits after the decimal point depending on the currency precision." }, "preAuthorizeAmount": { "type": "number", "format": "decimal", "nullable": true, "description": "Pre-authorize amount. The amount to pre-authorize before starting a session. Up to 5 digits after the decimal point depending on the currency precision." }, "incrementalPreAuthorizationAmount": { "type": "number", "nullable": true }, "taxID": { "type": "integer", "nullable": true, "description": "If Multi-tax Support has been enabled in the platform settings, you can provide the taxId for the tariff here. If you do not provide a value or provide `null`, the Default tax will be used. If Multi-tax Support has not been enabled, any provided value will be ignored." }, "chargePointElectricityRate": { "type": "boolean", "description": "Use the Electricity Rate of the Charge Point that is already attached and aims to track the electricity costs." }, "fallbackElectricityRateId": { "type": "integer", "nullable": true, "description": "When ChargePointElectricityRate is set to *false*, the Electricity Rate ID MUST be supplied in order the electricity rates for the tariff to be known." }, "markupPercentagePerKwh": { "type": "number", "nullable": true }, "markupFixedFeePerKwh": { "type": "number", "nullable": true }, "flexibleMarkUpAsFixedPerKwh": { "type": "object", "properties": { "defaultPrice": { "type": "number", "default": 0, "description": "Set price for the intervals not specified in `intervalPricing` field." }, "intervalPricing": { "type": "array", "items": { "type": "object", "properties": { "startsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The start time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "endsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The end time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "price": { "type": "number", "format": "decimal", "example": 1.23, "description": "The price that will apply for the given price period. Must include tax." } }, "required": [ "startsAt", "endsAt", "price" ], "description": "A specific price period. The `startsAt` and `endsAt` times should be provided in the local time zone and not in UTC. Depending on the tenant multi timezone configuration either the tenant timezone will be used, or the timezone specific to the corresponding resource." }, "description": "Variable-length time periods for markup pricing. Periods can have any duration and do not need to be uniform. Only explicitly configured periods are returned. Time slots not covered by any interval use the `markupFixedFeePerKwh` value. Overlapping intervals are not allowed." } }, "nullable": true, "description": "Set a different fixed markup for different time slots along the day. Applicable for `energy tou` only." }, "multiPricePerKwh": { "type": "array", "items": { "type": "object", "properties": { "firstKwh": { "type": "number", "example": 0.05 }, "lastKwh": { "type": "number", "example": 0.06, "nullable": true }, "feePerKwh": { "type": "number", "format": "decimal", "example": 0.07, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0.08, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstKwh" ] }, "description": "Create the price levels according to the kWh.
The first level must have zero value for **firstKwh**.
The last level must have an infinity value for **lastKwh**.
The **fisrtKwh** value on the current level must be equal to the **lastKwh** value on the previous one.
Instead of using a price per kWh there is the option for a flat fee per level. An example of price levels for kWh is given in the table below. | First kWh | Last kWh | Fee per kWh | Flat Fee | | --------- | ------------| ------------|------------ | | 0 | 5.00 | 0.00 | 2.00 | | 5.00 | 10.00 | 0.35 | 0.00 | | 10.00 | null | 0.40 | 0.00 | Applicable for standard tariff." }, "multiPricePerDuration": { "type": "array", "items": { "type": "object", "properties": { "firstUnit": { "type": "integer" }, "lastUnit": { "type": "integer", "example": 1, "nullable": true }, "feePerUnit": { "type": "number", "format": "decimal", "example": 0.05, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstUnit" ] }, "description": "Create the price levels according to the duration of the session from the time the charging started.
The first level must have zero value for **firstUnit**.
The last level must have an infinity value for **lastUnit**.
The **firstUnit** value on the current level must be greater with one unit from the **lastUnit** value on the previous level.
The Unit is created in the **pricePeriodInMinutes** property, the default one is 15 min.
There is the option of applying a flat fee per each level separately.
**Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `multiIdleFee`) will apply during idle periods. An example of price levels for duration is given in the table below. | First Unit | Last Unit | Fee per Unit | Flat Fee | | ----------- | ------------| -------------|------------ | | 0 | 8 | 0.50 | 0.00 | | 9 | 24 | 0.55 | 0.00 | | 25 | null | 0.00 | 10.00 | Applicable for standard tariff." }, "multiIdleFee": { "type": "array", "items": { "type": "object", "properties": { "firstUnit": { "type": "integer" }, "lastUnit": { "type": "integer", "example": 1, "nullable": true }, "feePerUnit": { "type": "number", "format": "decimal", "example": 0.05, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0.06, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstUnit" ] }, "description": "Different price levels could be created depending on the duration of the idle period.
The first level must have zero value for **firstUnit**.
The last level must have an infinity value for **lastUnit**.
The **firstUnit** value on the current level must be greater with one unit from the **lastUnit** value on the previous level.
The Unit is created in the **pricePeriodInMinutes** property, the default one is 15 min.
There is the option of applying a flat fee per each level separately.
Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `multiPricePerDuration`) will be paused. An example of price levels for idle periods is given in the table below. | First Unit | Last Unit | Fee per Unit | Flat Fee | | ----------- | ------------| -------------|------------ | | 0 | 2 | 0.30 | 0.00 | | 3 | 6 | 0.40 | 0.00 | | 7 | null | 0.00 | 0.00 | Applicable for standard tariff." }, "regularUsePeriod": { "type": "number", "nullable": true, "description": "In minutes. Only for the Peak power level tariff." }, "averagePowerLevels": { "type": "array", "items": { "type": "object", "properties": { "averagePowerUpToKw": { "type": "number" }, "pricePerMinute": { "type": "number" } }, "required": [ "averagePowerUpToKw", "pricePerMinute" ], "minItems": 2 } }, "peakPowerLevels": { "type": "array", "items": { "type": "object", "properties": { "peakPowerUpToKw": { "type": "number" }, "regularPricePerMinute": { "type": "number" }, "excessUsePricePerMin": { "type": "number" } }, "required": [ "peakPowerUpToKw", "regularPricePerMinute", "excessUsePricePerMin" ], "minItems": 2 } }, "timePeriods": { "type": "array", "items": { "type": "object", "properties": { "startTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "00:00", "description": "The 24-hour format should be used." }, "endTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "00:00", "description": "The 24-hour format should be used." } }, "required": [ "startTime", "endTime" ], "minItems": 1 } }, "pricePeriods": { "type": "object", "properties": { "connectionFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "energyFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "durationFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Duration fees for each time period. Applicable for standard_tod tariff. **Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `idleFeePeriods`) will apply during idle periods." }, "idleFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Idle fees for each time period. Applicable for standard_tod tariff. Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `durationFeePeriods`) will be paused." } } }, "daysWhenApplied": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "specialDates": { "type": "array", "items": { "type": "string", "format": "date" }, "example": "2022-01-30" }, "idleFeeGracePeriodMinutes": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee grace period (min). Optional. The interpretation of this field depends on `idleFeeGracePeriodMode`: - When mode is `idle_detection` (default): The user is given this grace period after idle state is detected (no charging) to remove the vehicle, before idle fee starts applying. - When mode is `session_start`: This represents the minimum session duration before idle fee applies. Idle fee will not be charged until the session has been active for at least this many minutes." }, "idlePricingPeriodInMinutes": { "type": "number", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging)." }, "connectionFeeMinimumSessionDuration": { "type": "integer", "nullable": true, "description": "Connection Fee Minimum Session Duration (min). Optional." }, "connectionFeeMinimumSessionEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection Fee Minimum Session Energy (kWh). Optional. Up to 5 digits after the decimal point depending on the currency precision." }, "durationFeeGracePeriod": { "type": "integer", "nullable": true, "description": "Duration Fee Grace Period (min). Optional." }, "pricePeriodInMinutes": { "type": "integer", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Charging period. In minutes. It defines the time-period for charging a fee. Example: If you select 15min then the EV-driver will be charged at the start of every 15min of EV-charging. Applicable for duration+energy and duration+energy time of day" }, "pricePeriods": { "type": "object", "properties": { "connectionFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "energyFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "durationFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Duration fees for each time period. Applicable for standard_tod tariff. **Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `idleFeePeriods`) will apply during idle periods." }, "idleFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Idle fees for each time period. Applicable for standard_tod tariff. Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `durationFeePeriods`) will be paused." } }, "minItems": 1 } } }, "description": "When left empty, this means that this is the standard pricing that would be applied in general without taking into consideration the day." }, "thresholdPriceForEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Price for kWh to be considered by Optimised charging for setting the charging periods." }, "priceForEnergyWhenOptimized": { "type": "number", "format": "decimal", "nullable": true }, "optimisedLabel": { "type": "string", "nullable": true }, "durationFeeFrom": { "type": "string", "format": "time", "nullable": true, "description": "Defined start time for the application of duration fees." }, "durationFeeTo": { "type": "string", "format": "time", "nullable": true, "description": "Defined end time for the application of duration fees." }, "subsidyIntegrationId": { "type": "integer", "nullable": true, "description": "**This property is deprecated** Use `subsidy.integrationId` instead. The subsidy integration id that should be applied for this tariff. Only valid for Energy ToU tariffs. Please use the admin panel for the specific integration id. Optional." }, "subsidy": { "type": "object", "properties": { "integrationId": { "type": "integer", "description": "The ID of the subsidy integration that is active on the tariff (or was active when the snapshot was taken)." }, "threshold": { "type": "number", "description": "The energy price threshold (in the operator's currency per kWh) above which the subsidy applies." }, "compensationRate": { "type": "number", "description": "The compensation rate as a percentage (e.g., 90 for 90%)." } }, "required": [ "integrationId", "threshold", "compensationRate" ], "description": "Subsidy parameters for this tariff. Only applicable for Energy ToU tariffs. Omitted when no subsidy is configured." }, "lockPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled the tariff of the charger will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for: - `duration+energy time of day` - it locks duration and energy price components - `energy tou` - it locks energy component only" }, "lockEnergyPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled the tariff of the charger will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for `standard_tod tariff`." }, "lockDurationPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled, the energy fee component of the tariff will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for `standard_tod tariff`." }, "lockIdlePriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled, the duration fee component of the tariff will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the whole duration of their session. Applicable only for `standard_tod tariff`" }, "stateOfChargeIdleThreshold": { "type": "integer", "enum": [ 75, 80, 85, 90, 95, 100 ], "nullable": true, "description": "Switches the session to idle when the SoC (%) exceeds the selected value. Leave empty to use the system wide setting. This option will take effect only if `Allow custom SoC (%) threshold per Tariff` is set in `Idle period detection` setting. This only applies to local charge points, it does not affect sessions on roaming charge points. Leave empty to use the system wide setting." }, "averagePowerIdleThreshold": { "type": "number", "format": "decimal", "minimum": 0, "maximum": 999999.99, "nullable": true, "description": "Sets the session to idle state when the average kW for the past 5 minutes is below the set threshold. This option will take effect only if `Allow custom power threshold per Tariff` is set in `Idle period detection` setting." } } }, "discountTariffSettings": { "type": "object", "properties": { "discountReferenceType": { "type": "string", "enum": [ "base_tariff", "specific_tariff", "roaming_tariff" ], "description": "Determines which tariff the discount is applied to. - `base_tariff` — the discount applies to the base tariff of the tariff group the discount tariff belongs to. - `specific_tariff` — the discount applies to the tariff identified by `referencedTariffId`. - `roaming_tariff` — the discount applies to the CPO wholesale tariff resolved at session time via OCPI. The exact source tariff is unknown at configuration time and varies per CPO partner and per session." }, "referencedTariffId": { "type": "integer", "description": "Present when `discountReferenceType=specific_tariff`. Omitted otherwise. Must reference a non-derived priced tariff owned by the same operator that is not itself `discount based`, `free`, or `charging not allowed`. Submitting a referenced tariff that violates these constraints is rejected with HTTP 422. Compatibility between a `base_tariff` discount and the actual base tariff of the tariff group is enforced when the discount tariff is added to a tariff group, and a `base_tariff` discount applied to a `free` or `charging not allowed` base tariff is rejected with HTTP 422 at that point. Prohibited when `discountReferenceType=roaming_tariff`." }, "discountMode": { "type": "string", "enum": [ "global", "per_element" ], "description": "Determines how the discount is applied. Required when `discountReferenceType` is `base_tariff` or `specific_tariff`. - `global` — a single `discountPercentage` is applied to every fee component of the referenced tariff. - `per_element` — different discount values are applied per fee component, configured via `discountElements`. Prohibited when `discountReferenceType=roaming_tariff` (roaming discounts are always applied globally)." }, "discountPercentage": { "type": "number", "format": "decimal", "minimum": 0, "maximum": 100, "description": "Present when `discountMode=global` and `discountReferenceType` is `base_tariff` or `specific_tariff`. Omitted otherwise. Percentage discount in the range `0` to `100` applied to every fee component of the referenced tariff. Out-of-range values are rejected with HTTP 422. Prohibited when `discountReferenceType=roaming_tariff` (use `discountValue` instead)." }, "discountType": { "type": "string", "enum": [ "percentage", "flat_amount" ], "description": "Present when `discountReferenceType=roaming_tariff`. Prohibited otherwise. - `percentage` — `discountValue` is interpreted as a percentage from 0 to 100. - `flat_amount` — `discountValue` is interpreted as a fixed currency amount to subtract from each CPO price component." }, "discountValue": { "type": "number", "format": "decimal", "minimum": 0, "description": "Present when `discountReferenceType=roaming_tariff`. Prohibited otherwise. The discount value, interpreted according to `discountType`. When `discountType` is `percentage`, the maximum is `100`. When `discountType` is `flat_amount`, the value represents a fixed currency amount with no upper bound." }, "discountElements": { "type": "array", "items": { "type": "object", "properties": { "serviceFeeType": { "type": "string", "enum": [ "flat", "connection", "energy", "charging_time", "idle_time", "min_price", "service_fee" ], "description": "The fee component of the referenced tariff that this discount applies to. Only discount-eligible fee types are accepted." }, "discountType": { "type": "string", "enum": [ "percentage", "flat_amount" ], "description": "- `percentage` — `discountValue` is interpreted as a percentage from 0 to 100. - `flat_amount` — `discountValue` is interpreted as a fixed amount in the operator's currency that is subtracted from the fee component." }, "discountValue": { "type": "number", "format": "decimal", "minimum": 0, "description": "The discount value, interpreted according to `discountType`. When `discountType` is `percentage`, the maximum is 100." } }, "required": [ "serviceFeeType", "discountType", "discountValue" ] }, "description": "Present when `discountMode=per_element` and `discountReferenceType` is `base_tariff` or `specific_tariff`. Omitted otherwise. Each entry configures a discount for a specific fee component of the referenced tariff. At least one entry is required. Prohibited when `discountReferenceType=roaming_tariff`." } }, "description": "Discount configuration for discount based tariffs. Present only when `type=discount based`, omitted otherwise." }, "stopSession": { "type": "object", "properties": { "timeLimitMinutes": { "type": "number", "nullable": true, "description": "Session max time. The maximum minutes a session is allowed to run. Skip for no time limit." }, "stopWhenEnergyExceedsKwh": { "type": "number", "nullable": true, "description": "The maximum energy (kWh) allowed per session. Skip for no limit." }, "stopWhenSocExceedsPercent": { "type": "integer", "minimum": 70, "maximum": 99, "nullable": true, "description": "Stop the session when the vehicle's reported State of Charge reaches or exceeds this value. If the charge point does not report SoC, this criterion is ignored. Accepts values between 70 and 99." } } }, "restrictions": { "type": "object", "properties": { "applyToUsersOfChargePointOwner": { "type": "boolean", "description": "Makes the tariff apply to users of the partner, who is set as owner of the charge point" }, "applyToUsersOfChargePointPartner": { "type": "boolean", "description": "Makes the tariff apply to users of the partner, who is set as owner of the charge point" }, "applyToUsersOfAllRoamingEmsps": { "type": "boolean", "description": "Makes the tariff apply to users of all eMSPs, which are roaming partners" }, "applyToAdHocUsers": { "type": "boolean", "description": "Makes the tariff valid for non-registered users(ad-hoc charging). Mutually exclusive with applyToAdHocOperatorIds." }, "adHocPreAuthorizeAmount": { "type": "number", "minimum": 0, "nullable": true, "description": "Sets the amount that would be blocked on the user's card at the start of the session. Required if applyToAdHocUsers is true or applyToAdHocOperatorIds is non-empty, and one of the following billing strategies is chosen: `Require payment method and authorize certain amount before starting session` or `Require payment method OR minimum amount in balance`." }, "adHocIncrementalPreAuthorizationAmount": { "type": "number", "nullable": true }, "adHocStopWhenPreAuthorizedAmountFallsBelow": { "type": "number", "description": "Set the minimum pre-authorized amount threshold. When the remaining ad hoc pre-authorized amount falls below this value, the charging session will automatically stop to prevent revenue loss." }, "applyToAdHocOperatorIds": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "An array of operator IDs. Makes the tariff apply to registered users from specific operators when charging ad-hoc (cross-operator charging without internal roaming). Mutually exclusive with applyToAdHocUsers." }, "applyToUsersOfPartners": { "type": "array", "items": { "type": "number" }, "description": "Users of specific Partners. Provide a list of partner IDs. Matches if the user is a invited to at least one of the partners." }, "applyToUsersWithGroups": { "type": "array", "items": { "type": "string" }, "description": "Users with a specific group. Provide a list of user groups. Matches if the user is a member of at least one of the groups. Note: Due to improvements in the user groups, this property could be used with some limitations: 1) The value(s) should exactly match the name(s) of the user groups. 2) It would not be possible to create a user group from here anymore. 3) If there are duplicates, the value would not be accepted." }, "applyToHomeChargingOwner": { "type": "boolean", "description": "Makes the tariff apply to the driver who owns the home charge point (the driver, not the partner that manages it)" }, "applyToHomeChargingSharedUsers": { "type": "boolean", "description": "Makes the tariff apply to the drivers the owner has shared the home charge point with (accepted shares only)" }, "applyToUserGroupIds": { "type": "array", "items": { "type": "number" }, "description": "An array of user group IDs. Users with a specific group. Provide a list of user group IDs. This restriction applies if the user is a member of at least one of the groups." }, "applyToUsersWithSubscriptions": { "type": "array", "items": { "type": "number" }, "description": "Users with a specific subscription plan. Provide a list of subscription plan IDs. Matches if the user has active one of the subscription plans." }, "applyToAuthorizationMethods": { "type": "array", "items": { "type": "string", "enum": [ "id_tag", "mac_address", "user_device", "plug_and_charge", "plug_and_charge_iso15118" ] }, "description": "The tariff applies to local users (non-roaming) who authorize using any of the selected methods. When omitted or empty, the tariff applies regardless of authorization method. Values align with the `Authorization.method` property: - `id_tag` - Authorization via physical RFID card - `mac_address` - Authorization via vehicle MAC address (AutoCharge) - `user_device` - Authorization via mobile app or web portal - `plug_and_charge` - Authorization via Plug & Charge protocol - `plug_and_charge_iso15118` - Authorization via ISO15118 Plug & Charge protocol" }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "The date from which the tariff becomes valid." }, "endDate": { "type": "string", "format": "date", "nullable": true, "description": "The expiry date of the tariff. The tariff is valid until this date inclusive." } } }, "partner": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "The assigned Partner will have access to make changes to the tariff." } } }, "display": { "type": "object", "properties": { "defaultPriceInformation": { "type": "string", "maxLength": 150, "nullable": true, "description": "Deprecated: use the tariff group resource to manage this field." }, "defaultPriceInformationOffline": { "type": "string", "maxLength": 150, "nullable": true, "description": "Deprecated: use the tariff group resource to manage this field." }, "priceInformation": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `priceInformationLocalized` instead.** The scalar field only carries the default-locale value and cannot round-trip multi-locale content. The information that would be shown on the display of the charge point for users that are eligible for this tariff." }, "priceInformationLocalized": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "totalCostInformation": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `totalCostInformationLocalized` instead.** The scalar field only carries the default-locale value and cannot round-trip multi-locale content. Additional information that would be displayed on the charge point when the session ends, along with the total fees for energy, duration and idle." }, "totalCostInformationLocalized": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "plainTextModeEnabled": { "type": "boolean", "default": false, "description": "When `true`, the display text is delivered to the charge point without rich text formatting." } } }, "integrationId": { "type": "integer", "nullable": true, "description": "References the internal integration configuration that enables this tariff type" }, "externalId": { "type": "string", "nullable": true, "description": "Used to store custom information, usually used for external references or metadata to the resource." }, "type": { "type": "string", "enum": [ "free", "flat rate", "duration+energy", "duration+energy time of day", "energy tou", "standard", "charging not allowed", "average power levels", "peak power levels", "standard_tod", "optimised dynamic pricing", "discount based" ], "description": "Setting the type to `charging not allowed` or `free` is enough for creating the particular type of tariff." } }, "required": [ "name", "type" ] } } } }, "responses": { "201": { "description": "Tariff created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariffs/v1.0/{tariff}", "method": "GET", "operationId": "tariffRead", "summary": "Tariff / Read", "description": "Get a tariff", "tags": [ "resource / tariffs" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariffs/v1.0/{tariff}", "method": "PUT", "operationId": "tariffUpdate", "summary": "Tariff / Update", "description": "Update a tariff", "tags": [ "resource / tariffs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "additionalInformation": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "learnMoreUrl": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "dayTariffStart": { "type": "string", "format": "time", "description": "A time when the day begins" }, "nightTariffStart": { "type": "string", "format": "time", "description": "A time when the night begins" }, "pricing": { "type": "object", "properties": { "pricePerSession": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per session. Only applicable with flat rate tariffs. Up to 5 digits after the decimal point depending on the currency precision." }, "connectionFee": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection fee. A fixed fee that is applied at the start of the charging session. Up to 5 digits after the decimal point depending on the currency precision." }, "pricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh. Up to 5 digits after the decimal point depending on the currency precision." }, "dayPricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision." }, "nightPricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision." }, "pricePeriodInMinutes": { "type": "integer", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Charging period. In minutes. It defines the time-period for charging a fee. Example: If you select 15min then the EV-driver will be charged at the start of every 15min of EV-charging. Applicable for duration+energy and duration+energy time of day" }, "pricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period. Applicable for duration+energy. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`idleFeePerMinute`), the regular duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "durationFeeLimit": { "type": "number", "format": "decimal", "nullable": true, "description": "Duration fee limit for the whole session if fee is applied." }, "durationFeeCapMinutes": { "type": "integer", "nullable": true, "description": "Maximum billable charging duration in minutes. A value of zero means no duration fee is charged. Mutually exclusive with durationFeeLimit." }, "dayPricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`dayIdleFeePerMinute`), the regular day duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "nightPricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`nightIdleFeePerMinute`), the regular night duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "dayIdleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. When configured, this fee applies during idle periods (when no charging is occurring) and replaces the regular day duration fee (`dayPricePerPeriod`). If not configured, the regular day duration fee continues to apply during idle periods." }, "nightIdleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. When configured, this fee applies during idle periods (when no charging is occurring) and replaces the regular night duration fee (`nightPricePerPeriod`). If not configured, the regular night duration fee continues to apply during idle periods." }, "idleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging). Up to 5 digits after the decimal point depending on the currency precision. **For duration+energy tariffs:** When configured, this fee applies during idle periods and replaces the regular duration fee (`pricePerPeriod`). If not configured, the regular duration fee continues to apply during idle periods." }, "idleFeeGracePeriodMinutes": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee grace period (min). Optional. The interpretation of this field depends on `idleFeeGracePeriodMode`: - When mode is `idle_detection` (default): The user is given this grace period after idle state is detected (no charging) to remove the vehicle, before idle fee starts applying. - When mode is `session_start`: This represents the minimum session duration before idle fee applies. Idle fee will not be charged until the session has been active for at least this many minutes." }, "idleFeeGracePeriodMode": { "type": "string", "enum": [ "idle_detection", "session_start" ], "description": "Determines when the idle fee grace period timer starts counting. - `idle_detection` (default): Grace period begins when idle state is detected (vehicle stops charging but remains connected). - `session_start`: Grace period begins from session start time. Idle fee will not apply until the session has been active for at least the grace period duration. Applicable tariff types: `duration+energy`, `duration+energy time of day`, `energy tou`, `standard_tod`." }, "idlePricingPeriodInMinutes": { "type": "number", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging)." }, "idleFeePeriodStart": { "type": "string", "format": "time", "nullable": true, "description": "Defined start time for the application of idle fee." }, "idleFeePeriodEnd": { "type": "string", "format": "time", "nullable": true, "description": "Defined end time for the application of idle fee." }, "idleFeeLimit": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee limit for the whole session if fee is applied." }, "idleFeeCapMinutes": { "type": "integer", "nullable": true, "description": "Maximum billable idle time in minutes. A value of zero means no idle fee is charged. Mutually exclusive with idleFeeLimit." }, "connectionFeeMinimumSessionDuration": { "type": "integer", "nullable": true, "description": "Connection Fee Minimum Session Duration (min). Optional." }, "connectionFeeMinimumSessionEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection Fee Minimum Session Energy (kWh). Optional. Up to 5 digits after the decimal point depending on the currency precision." }, "durationFeeGracePeriod": { "type": "integer", "nullable": true, "description": "Duration Fee Grace Period (min). Optional." }, "minPrice": { "type": "number", "format": "decimal", "nullable": true, "description": "Min. price. Sets a minimum total amount per session. This is helpful in the case your payment service provider has a minimum transaction size or high transaction fees and you want to make sure to have a positive ROI per transaction. Up to 5 digits after the decimal point depending on the currency precision." }, "preAuthorizeAmount": { "type": "number", "format": "decimal", "nullable": true, "description": "Pre-authorize amount. The amount to pre-authorize before starting a session. Up to 5 digits after the decimal point depending on the currency precision." }, "incrementalPreAuthorizationAmount": { "type": "number", "nullable": true }, "taxID": { "type": "integer", "nullable": true, "description": "If Multi-tax Support has been enabled in the platform settings, you can provide the taxId for the tariff here. If you do not provide a value or provide `null`, the Default tax will be used. If Multi-tax Support has not been enabled, any provided value will be ignored." }, "chargePointElectricityRate": { "type": "boolean", "description": "Use the Electricity Rate of the Charge Point that is already attached and aims to track the electricity costs." }, "fallbackElectricityRateId": { "type": "integer", "nullable": true, "description": "When ChargePointElectricityRate is set to *false*, the Electricity Rate ID MUST be supplied in order the electricity rates for the tariff to be known." }, "markupPercentagePerKwh": { "type": "number", "nullable": true }, "markupFixedFeePerKwh": { "type": "number", "nullable": true }, "flexibleMarkUpAsFixedPerKwh": { "type": "object", "properties": { "defaultPrice": { "type": "number", "default": 0, "description": "Set price for the intervals not specified in `intervalPricing` field." }, "intervalPricing": { "type": "array", "items": { "type": "object", "properties": { "startsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The start time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "endsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The end time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "price": { "type": "number", "format": "decimal", "example": 1.23, "description": "The price that will apply for the given price period. Must include tax." } }, "required": [ "startsAt", "endsAt", "price" ], "description": "A specific price period. The `startsAt` and `endsAt` times should be provided in the local time zone and not in UTC. Depending on the tenant multi timezone configuration either the tenant timezone will be used, or the timezone specific to the corresponding resource." }, "description": "Variable-length time periods for markup pricing. Periods can have any duration and do not need to be uniform. Only explicitly configured periods are returned. Time slots not covered by any interval use the `markupFixedFeePerKwh` value. Overlapping intervals are not allowed." } }, "nullable": true, "description": "Set a different fixed markup for different time slots along the day. Applicable for `energy tou` only." }, "multiPricePerKwh": { "type": "array", "items": { "type": "object", "properties": { "firstKwh": { "type": "number", "example": 0.05 }, "lastKwh": { "type": "number", "example": 0.06, "nullable": true }, "feePerKwh": { "type": "number", "format": "decimal", "example": 0.07, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0.08, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstKwh" ] }, "description": "Create the price levels according to the kWh.
The first level must have zero value for **firstKwh**.
The last level must have an infinity value for **lastKwh**.
The **fisrtKwh** value on the current level must be equal to the **lastKwh** value on the previous one.
Instead of using a price per kWh there is the option for a flat fee per level. An example of price levels for kWh is given in the table below. | First kWh | Last kWh | Fee per kWh | Flat Fee | | --------- | ------------| ------------|------------ | | 0 | 5.00 | 0.00 | 2.00 | | 5.00 | 10.00 | 0.35 | 0.00 | | 10.00 | null | 0.40 | 0.00 | Applicable for standard tariff." }, "multiPricePerDuration": { "type": "array", "items": { "type": "object", "properties": { "firstUnit": { "type": "integer" }, "lastUnit": { "type": "integer", "example": 1, "nullable": true }, "feePerUnit": { "type": "number", "format": "decimal", "example": 0.05, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstUnit" ] }, "description": "Create the price levels according to the duration of the session from the time the charging started.
The first level must have zero value for **firstUnit**.
The last level must have an infinity value for **lastUnit**.
The **firstUnit** value on the current level must be greater with one unit from the **lastUnit** value on the previous level.
The Unit is created in the **pricePeriodInMinutes** property, the default one is 15 min.
There is the option of applying a flat fee per each level separately.
**Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `multiIdleFee`) will apply during idle periods. An example of price levels for duration is given in the table below. | First Unit | Last Unit | Fee per Unit | Flat Fee | | ----------- | ------------| -------------|------------ | | 0 | 8 | 0.50 | 0.00 | | 9 | 24 | 0.55 | 0.00 | | 25 | null | 0.00 | 10.00 | Applicable for standard tariff." }, "multiIdleFee": { "type": "array", "items": { "type": "object", "properties": { "firstUnit": { "type": "integer" }, "lastUnit": { "type": "integer", "example": 1, "nullable": true }, "feePerUnit": { "type": "number", "format": "decimal", "example": 0.05, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0.06, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstUnit" ] }, "description": "Different price levels could be created depending on the duration of the idle period.
The first level must have zero value for **firstUnit**.
The last level must have an infinity value for **lastUnit**.
The **firstUnit** value on the current level must be greater with one unit from the **lastUnit** value on the previous level.
The Unit is created in the **pricePeriodInMinutes** property, the default one is 15 min.
There is the option of applying a flat fee per each level separately.
Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `multiPricePerDuration`) will be paused. An example of price levels for idle periods is given in the table below. | First Unit | Last Unit | Fee per Unit | Flat Fee | | ----------- | ------------| -------------|------------ | | 0 | 2 | 0.30 | 0.00 | | 3 | 6 | 0.40 | 0.00 | | 7 | null | 0.00 | 0.00 | Applicable for standard tariff." }, "regularUsePeriod": { "type": "number", "nullable": true, "description": "In minutes. Only for the Peak power level tariff." }, "averagePowerLevels": { "type": "array", "items": { "type": "object", "properties": { "averagePowerUpToKw": { "type": "number" }, "pricePerMinute": { "type": "number" } }, "required": [ "averagePowerUpToKw", "pricePerMinute" ], "minItems": 2 } }, "peakPowerLevels": { "type": "array", "items": { "type": "object", "properties": { "peakPowerUpToKw": { "type": "number" }, "regularPricePerMinute": { "type": "number" }, "excessUsePricePerMin": { "type": "number" } }, "required": [ "peakPowerUpToKw", "regularPricePerMinute", "excessUsePricePerMin" ], "minItems": 2 } }, "timePeriods": { "type": "array", "items": { "type": "object", "properties": { "startTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "00:00", "description": "The 24-hour format should be used." }, "endTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "00:00", "description": "The 24-hour format should be used." } }, "required": [ "startTime", "endTime" ], "minItems": 1 } }, "pricePeriods": { "type": "object", "properties": { "connectionFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "energyFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "durationFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Duration fees for each time period. Applicable for standard_tod tariff. **Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `idleFeePeriods`) will apply during idle periods." }, "idleFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Idle fees for each time period. Applicable for standard_tod tariff. Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `durationFeePeriods`) will be paused." } } }, "daysWhenApplied": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "specialDates": { "type": "array", "items": { "type": "string", "format": "date" }, "example": "2022-01-30" }, "idleFeeGracePeriodMinutes": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee grace period (min). Optional. The interpretation of this field depends on `idleFeeGracePeriodMode`: - When mode is `idle_detection` (default): The user is given this grace period after idle state is detected (no charging) to remove the vehicle, before idle fee starts applying. - When mode is `session_start`: This represents the minimum session duration before idle fee applies. Idle fee will not be charged until the session has been active for at least this many minutes." }, "idlePricingPeriodInMinutes": { "type": "number", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging)." }, "connectionFeeMinimumSessionDuration": { "type": "integer", "nullable": true, "description": "Connection Fee Minimum Session Duration (min). Optional." }, "connectionFeeMinimumSessionEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection Fee Minimum Session Energy (kWh). Optional. Up to 5 digits after the decimal point depending on the currency precision." }, "durationFeeGracePeriod": { "type": "integer", "nullable": true, "description": "Duration Fee Grace Period (min). Optional." }, "pricePeriodInMinutes": { "type": "integer", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Charging period. In minutes. It defines the time-period for charging a fee. Example: If you select 15min then the EV-driver will be charged at the start of every 15min of EV-charging. Applicable for duration+energy and duration+energy time of day" }, "pricePeriods": { "type": "object", "properties": { "connectionFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "energyFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "durationFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Duration fees for each time period. Applicable for standard_tod tariff. **Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `idleFeePeriods`) will apply during idle periods." }, "idleFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Idle fees for each time period. Applicable for standard_tod tariff. Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `durationFeePeriods`) will be paused." } }, "minItems": 1 } } }, "description": "When left empty, this means that this is the standard pricing that would be applied in general without taking into consideration the day." }, "thresholdPriceForEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Price for kWh to be considered by Optimised charging for setting the charging periods." }, "priceForEnergyWhenOptimized": { "type": "number", "format": "decimal", "nullable": true }, "optimisedLabel": { "type": "string", "nullable": true }, "durationFeeFrom": { "type": "string", "format": "time", "nullable": true, "description": "Defined start time for the application of duration fees." }, "durationFeeTo": { "type": "string", "format": "time", "nullable": true, "description": "Defined end time for the application of duration fees." }, "subsidyIntegrationId": { "type": "integer", "nullable": true, "description": "**This property is deprecated** Use `subsidy.integrationId` instead. The subsidy integration id that should be applied for this tariff. Only valid for Energy ToU tariffs. Please use the admin panel for the specific integration id. Optional." }, "subsidy": { "type": "object", "properties": { "integrationId": { "type": "integer", "description": "The ID of the subsidy integration that is active on the tariff (or was active when the snapshot was taken)." }, "threshold": { "type": "number", "description": "The energy price threshold (in the operator's currency per kWh) above which the subsidy applies." }, "compensationRate": { "type": "number", "description": "The compensation rate as a percentage (e.g., 90 for 90%)." } }, "required": [ "integrationId", "threshold", "compensationRate" ], "description": "Subsidy parameters for this tariff. Only applicable for Energy ToU tariffs. Omitted when no subsidy is configured." }, "lockPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled the tariff of the charger will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for: - `duration+energy time of day` - it locks duration and energy price components - `energy tou` - it locks energy component only" }, "lockEnergyPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled the tariff of the charger will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for `standard_tod tariff`." }, "lockDurationPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled, the energy fee component of the tariff will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for `standard_tod tariff`." }, "lockIdlePriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled, the duration fee component of the tariff will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the whole duration of their session. Applicable only for `standard_tod tariff`" }, "stateOfChargeIdleThreshold": { "type": "integer", "enum": [ 75, 80, 85, 90, 95, 100 ], "nullable": true, "description": "Switches the session to idle when the SoC (%) exceeds the selected value. Leave empty to use the system wide setting. This option will take effect only if `Allow custom SoC (%) threshold per Tariff` is set in `Idle period detection` setting. This only applies to local charge points, it does not affect sessions on roaming charge points. Leave empty to use the system wide setting." }, "averagePowerIdleThreshold": { "type": "number", "format": "decimal", "minimum": 0, "maximum": 999999.99, "nullable": true, "description": "Sets the session to idle state when the average kW for the past 5 minutes is below the set threshold. This option will take effect only if `Allow custom power threshold per Tariff` is set in `Idle period detection` setting." } } }, "discountTariffSettings": { "type": "object", "properties": { "discountReferenceType": { "type": "string", "enum": [ "base_tariff", "specific_tariff", "roaming_tariff" ], "description": "Determines which tariff the discount is applied to. - `base_tariff` — the discount applies to the base tariff of the tariff group the discount tariff belongs to. - `specific_tariff` — the discount applies to the tariff identified by `referencedTariffId`. - `roaming_tariff` — the discount applies to the CPO wholesale tariff resolved at session time via OCPI. The exact source tariff is unknown at configuration time and varies per CPO partner and per session." }, "referencedTariffId": { "type": "integer", "description": "Present when `discountReferenceType=specific_tariff`. Omitted otherwise. Must reference a non-derived priced tariff owned by the same operator that is not itself `discount based`, `free`, or `charging not allowed`. Submitting a referenced tariff that violates these constraints is rejected with HTTP 422. Compatibility between a `base_tariff` discount and the actual base tariff of the tariff group is enforced when the discount tariff is added to a tariff group, and a `base_tariff` discount applied to a `free` or `charging not allowed` base tariff is rejected with HTTP 422 at that point. Prohibited when `discountReferenceType=roaming_tariff`." }, "discountMode": { "type": "string", "enum": [ "global", "per_element" ], "description": "Determines how the discount is applied. Required when `discountReferenceType` is `base_tariff` or `specific_tariff`. - `global` — a single `discountPercentage` is applied to every fee component of the referenced tariff. - `per_element` — different discount values are applied per fee component, configured via `discountElements`. Prohibited when `discountReferenceType=roaming_tariff` (roaming discounts are always applied globally)." }, "discountPercentage": { "type": "number", "format": "decimal", "minimum": 0, "maximum": 100, "description": "Present when `discountMode=global` and `discountReferenceType` is `base_tariff` or `specific_tariff`. Omitted otherwise. Percentage discount in the range `0` to `100` applied to every fee component of the referenced tariff. Out-of-range values are rejected with HTTP 422. Prohibited when `discountReferenceType=roaming_tariff` (use `discountValue` instead)." }, "discountType": { "type": "string", "enum": [ "percentage", "flat_amount" ], "description": "Present when `discountReferenceType=roaming_tariff`. Prohibited otherwise. - `percentage` — `discountValue` is interpreted as a percentage from 0 to 100. - `flat_amount` — `discountValue` is interpreted as a fixed currency amount to subtract from each CPO price component." }, "discountValue": { "type": "number", "format": "decimal", "minimum": 0, "description": "Present when `discountReferenceType=roaming_tariff`. Prohibited otherwise. The discount value, interpreted according to `discountType`. When `discountType` is `percentage`, the maximum is `100`. When `discountType` is `flat_amount`, the value represents a fixed currency amount with no upper bound." }, "discountElements": { "type": "array", "items": { "type": "object", "properties": { "serviceFeeType": { "type": "string", "enum": [ "flat", "connection", "energy", "charging_time", "idle_time", "min_price", "service_fee" ], "description": "The fee component of the referenced tariff that this discount applies to. Only discount-eligible fee types are accepted." }, "discountType": { "type": "string", "enum": [ "percentage", "flat_amount" ], "description": "- `percentage` — `discountValue` is interpreted as a percentage from 0 to 100. - `flat_amount` — `discountValue` is interpreted as a fixed amount in the operator's currency that is subtracted from the fee component." }, "discountValue": { "type": "number", "format": "decimal", "minimum": 0, "description": "The discount value, interpreted according to `discountType`. When `discountType` is `percentage`, the maximum is 100." } }, "required": [ "serviceFeeType", "discountType", "discountValue" ] }, "description": "Present when `discountMode=per_element` and `discountReferenceType` is `base_tariff` or `specific_tariff`. Omitted otherwise. Each entry configures a discount for a specific fee component of the referenced tariff. At least one entry is required. Prohibited when `discountReferenceType=roaming_tariff`." } }, "description": "Discount configuration for discount based tariffs. Present only when `type=discount based`, omitted otherwise." }, "stopSession": { "type": "object", "properties": { "timeLimitMinutes": { "type": "number", "nullable": true, "description": "Session max time. The maximum minutes a session is allowed to run. Skip for no time limit." }, "stopWhenEnergyExceedsKwh": { "type": "number", "nullable": true, "description": "The maximum energy (kWh) allowed per session. Skip for no limit." }, "stopWhenSocExceedsPercent": { "type": "integer", "minimum": 70, "maximum": 99, "nullable": true, "description": "Stop the session when the vehicle's reported State of Charge reaches or exceeds this value. If the charge point does not report SoC, this criterion is ignored. Accepts values between 70 and 99." } } }, "restrictions": { "type": "object", "properties": { "applyToUsersOfChargePointOwner": { "type": "boolean", "description": "Makes the tariff apply to users of the partner, who is set as owner of the charge point" }, "applyToUsersOfChargePointPartner": { "type": "boolean", "description": "Makes the tariff apply to users of the partner, who is set as owner of the charge point" }, "applyToUsersOfAllRoamingEmsps": { "type": "boolean", "description": "Makes the tariff apply to users of all eMSPs, which are roaming partners" }, "applyToAdHocUsers": { "type": "boolean", "description": "Makes the tariff valid for non-registered users(ad-hoc charging). Mutually exclusive with applyToAdHocOperatorIds." }, "adHocPreAuthorizeAmount": { "type": "number", "minimum": 0, "nullable": true, "description": "Sets the amount that would be blocked on the user's card at the start of the session. Required if applyToAdHocUsers is true or applyToAdHocOperatorIds is non-empty, and one of the following billing strategies is chosen: `Require payment method and authorize certain amount before starting session` or `Require payment method OR minimum amount in balance`." }, "adHocIncrementalPreAuthorizationAmount": { "type": "number", "nullable": true }, "adHocStopWhenPreAuthorizedAmountFallsBelow": { "type": "number", "description": "Set the minimum pre-authorized amount threshold. When the remaining ad hoc pre-authorized amount falls below this value, the charging session will automatically stop to prevent revenue loss." }, "applyToAdHocOperatorIds": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "An array of operator IDs. Makes the tariff apply to registered users from specific operators when charging ad-hoc (cross-operator charging without internal roaming). Mutually exclusive with applyToAdHocUsers." }, "applyToUsersOfPartners": { "type": "array", "items": { "type": "number" }, "description": "Users of specific Partners. Provide a list of partner IDs. Matches if the user is a invited to at least one of the partners." }, "applyToUsersWithGroups": { "type": "array", "items": { "type": "string" }, "description": "Users with a specific group. Provide a list of user groups. Matches if the user is a member of at least one of the groups. Note: Due to improvements in the user groups, this property could be used with some limitations: 1) The value(s) should exactly match the name(s) of the user groups. 2) It would not be possible to create a user group from here anymore. 3) If there are duplicates, the value would not be accepted." }, "applyToHomeChargingOwner": { "type": "boolean", "description": "Makes the tariff apply to the driver who owns the home charge point (the driver, not the partner that manages it)" }, "applyToHomeChargingSharedUsers": { "type": "boolean", "description": "Makes the tariff apply to the drivers the owner has shared the home charge point with (accepted shares only)" }, "applyToUserGroupIds": { "type": "array", "items": { "type": "number" }, "description": "An array of user group IDs. Users with a specific group. Provide a list of user group IDs. This restriction applies if the user is a member of at least one of the groups." }, "applyToUsersWithSubscriptions": { "type": "array", "items": { "type": "number" }, "description": "Users with a specific subscription plan. Provide a list of subscription plan IDs. Matches if the user has active one of the subscription plans." }, "applyToAuthorizationMethods": { "type": "array", "items": { "type": "string", "enum": [ "id_tag", "mac_address", "user_device", "plug_and_charge", "plug_and_charge_iso15118" ] }, "description": "The tariff applies to local users (non-roaming) who authorize using any of the selected methods. When omitted or empty, the tariff applies regardless of authorization method. Values align with the `Authorization.method` property: - `id_tag` - Authorization via physical RFID card - `mac_address` - Authorization via vehicle MAC address (AutoCharge) - `user_device` - Authorization via mobile app or web portal - `plug_and_charge` - Authorization via Plug & Charge protocol - `plug_and_charge_iso15118` - Authorization via ISO15118 Plug & Charge protocol" }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "The date from which the tariff becomes valid." }, "endDate": { "type": "string", "format": "date", "nullable": true, "description": "The expiry date of the tariff. The tariff is valid until this date inclusive." } } }, "partner": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "The assigned Partner will have access to make changes to the tariff." } } }, "display": { "type": "object", "properties": { "defaultPriceInformation": { "type": "string", "maxLength": 150, "nullable": true, "description": "Deprecated: use the tariff group resource to manage this field." }, "defaultPriceInformationOffline": { "type": "string", "maxLength": 150, "nullable": true, "description": "Deprecated: use the tariff group resource to manage this field." }, "priceInformation": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `priceInformationLocalized` instead.** The scalar field only carries the default-locale value and cannot round-trip multi-locale content. The information that would be shown on the display of the charge point for users that are eligible for this tariff." }, "priceInformationLocalized": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "totalCostInformation": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `totalCostInformationLocalized` instead.** The scalar field only carries the default-locale value and cannot round-trip multi-locale content. Additional information that would be displayed on the charge point when the session ends, along with the total fees for energy, duration and idle." }, "totalCostInformationLocalized": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "plainTextModeEnabled": { "type": "boolean", "default": false, "description": "When `true`, the display text is delivered to the charge point without rich text formatting." } } }, "integrationId": { "type": "integer", "nullable": true, "description": "References the internal integration configuration that enables this tariff type" }, "externalId": { "type": "string", "nullable": true, "description": "Used to store custom information, usually used for external references or metadata to the resource." }, "type": { "type": "string", "enum": [ "free", "flat rate", "duration+energy", "duration+energy time of day", "energy tou", "standard", "charging not allowed", "average power levels", "peak power levels", "standard_tod", "optimised dynamic pricing", "discount based" ], "description": "Setting the type to `charging not allowed` or `free` is enough for creating the particular type of tariff." } }, "required": [ "name", "type" ] } } } }, "responses": { "200": { "description": "Updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariffs/v1.0/{tariff}", "method": "DELETE", "operationId": "tariffDelete", "summary": "Tariff / Delete", "description": "Delete a tariff", "tags": [ "resource / tariffs" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariffs/v1.0/{tariff}", "method": "PATCH", "operationId": "tariffPartialUpdate", "summary": "Tariff / Partial Update", "description": "Partially update a tariff. Only the fields included in the request body are updated. Omitted fields retain their current values. Nested objects are merged recursively, while arrays are fully replaced. The tariff type cannot be changed via PATCH — use PUT with the full payload instead.", "tags": [ "resource / tariffs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "additionalInformation": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "learnMoreUrl": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "dayTariffStart": { "type": "string", "format": "time", "description": "A time when the day begins" }, "nightTariffStart": { "type": "string", "format": "time", "description": "A time when the night begins" }, "pricing": { "type": "object", "properties": { "pricePerSession": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per session. Only applicable with flat rate tariffs. Up to 5 digits after the decimal point depending on the currency precision." }, "connectionFee": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection fee. A fixed fee that is applied at the start of the charging session. Up to 5 digits after the decimal point depending on the currency precision." }, "pricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh. Up to 5 digits after the decimal point depending on the currency precision." }, "dayPricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision." }, "nightPricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision." }, "pricePeriodInMinutes": { "type": "integer", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Charging period. In minutes. It defines the time-period for charging a fee. Example: If you select 15min then the EV-driver will be charged at the start of every 15min of EV-charging. Applicable for duration+energy and duration+energy time of day" }, "pricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period. Applicable for duration+energy. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`idleFeePerMinute`), the regular duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "durationFeeLimit": { "type": "number", "format": "decimal", "nullable": true, "description": "Duration fee limit for the whole session if fee is applied." }, "durationFeeCapMinutes": { "type": "integer", "nullable": true, "description": "Maximum billable charging duration in minutes. A value of zero means no duration fee is charged. Mutually exclusive with durationFeeLimit." }, "dayPricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`dayIdleFeePerMinute`), the regular day duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "nightPricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`nightIdleFeePerMinute`), the regular night duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "dayIdleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. When configured, this fee applies during idle periods (when no charging is occurring) and replaces the regular day duration fee (`dayPricePerPeriod`). If not configured, the regular day duration fee continues to apply during idle periods." }, "nightIdleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. When configured, this fee applies during idle periods (when no charging is occurring) and replaces the regular night duration fee (`nightPricePerPeriod`). If not configured, the regular night duration fee continues to apply during idle periods." }, "idleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging). Up to 5 digits after the decimal point depending on the currency precision. **For duration+energy tariffs:** When configured, this fee applies during idle periods and replaces the regular duration fee (`pricePerPeriod`). If not configured, the regular duration fee continues to apply during idle periods." }, "idleFeeGracePeriodMinutes": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee grace period (min). Optional. The interpretation of this field depends on `idleFeeGracePeriodMode`: - When mode is `idle_detection` (default): The user is given this grace period after idle state is detected (no charging) to remove the vehicle, before idle fee starts applying. - When mode is `session_start`: This represents the minimum session duration before idle fee applies. Idle fee will not be charged until the session has been active for at least this many minutes." }, "idleFeeGracePeriodMode": { "type": "string", "enum": [ "idle_detection", "session_start" ], "description": "Determines when the idle fee grace period timer starts counting. - `idle_detection` (default): Grace period begins when idle state is detected (vehicle stops charging but remains connected). - `session_start`: Grace period begins from session start time. Idle fee will not apply until the session has been active for at least the grace period duration. Applicable tariff types: `duration+energy`, `duration+energy time of day`, `energy tou`, `standard_tod`." }, "idlePricingPeriodInMinutes": { "type": "number", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging)." }, "idleFeePeriodStart": { "type": "string", "format": "time", "nullable": true, "description": "Defined start time for the application of idle fee." }, "idleFeePeriodEnd": { "type": "string", "format": "time", "nullable": true, "description": "Defined end time for the application of idle fee." }, "idleFeeLimit": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee limit for the whole session if fee is applied." }, "idleFeeCapMinutes": { "type": "integer", "nullable": true, "description": "Maximum billable idle time in minutes. A value of zero means no idle fee is charged. Mutually exclusive with idleFeeLimit." }, "connectionFeeMinimumSessionDuration": { "type": "integer", "nullable": true, "description": "Connection Fee Minimum Session Duration (min). Optional." }, "connectionFeeMinimumSessionEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection Fee Minimum Session Energy (kWh). Optional. Up to 5 digits after the decimal point depending on the currency precision." }, "durationFeeGracePeriod": { "type": "integer", "nullable": true, "description": "Duration Fee Grace Period (min). Optional." }, "minPrice": { "type": "number", "format": "decimal", "nullable": true, "description": "Min. price. Sets a minimum total amount per session. This is helpful in the case your payment service provider has a minimum transaction size or high transaction fees and you want to make sure to have a positive ROI per transaction. Up to 5 digits after the decimal point depending on the currency precision." }, "preAuthorizeAmount": { "type": "number", "format": "decimal", "nullable": true, "description": "Pre-authorize amount. The amount to pre-authorize before starting a session. Up to 5 digits after the decimal point depending on the currency precision." }, "incrementalPreAuthorizationAmount": { "type": "number", "nullable": true }, "taxID": { "type": "integer", "nullable": true, "description": "If Multi-tax Support has been enabled in the platform settings, you can provide the taxId for the tariff here. If you do not provide a value or provide `null`, the Default tax will be used. If Multi-tax Support has not been enabled, any provided value will be ignored." }, "chargePointElectricityRate": { "type": "boolean", "description": "Use the Electricity Rate of the Charge Point that is already attached and aims to track the electricity costs." }, "fallbackElectricityRateId": { "type": "integer", "nullable": true, "description": "When ChargePointElectricityRate is set to *false*, the Electricity Rate ID MUST be supplied in order the electricity rates for the tariff to be known." }, "markupPercentagePerKwh": { "type": "number", "nullable": true }, "markupFixedFeePerKwh": { "type": "number", "nullable": true }, "flexibleMarkUpAsFixedPerKwh": { "type": "object", "properties": { "defaultPrice": { "type": "number", "default": 0, "description": "Set price for the intervals not specified in `intervalPricing` field." }, "intervalPricing": { "type": "array", "items": { "type": "object", "properties": { "startsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The start time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "endsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The end time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "price": { "type": "number", "format": "decimal", "example": 1.23, "description": "The price that will apply for the given price period. Must include tax." } }, "required": [ "startsAt", "endsAt", "price" ], "description": "A specific price period. The `startsAt` and `endsAt` times should be provided in the local time zone and not in UTC. Depending on the tenant multi timezone configuration either the tenant timezone will be used, or the timezone specific to the corresponding resource." }, "description": "Variable-length time periods for markup pricing. Periods can have any duration and do not need to be uniform. Only explicitly configured periods are returned. Time slots not covered by any interval use the `markupFixedFeePerKwh` value. Overlapping intervals are not allowed." } }, "nullable": true, "description": "Set a different fixed markup for different time slots along the day. Applicable for `energy tou` only." }, "multiPricePerKwh": { "type": "array", "items": { "type": "object", "properties": { "firstKwh": { "type": "number", "example": 0.05 }, "lastKwh": { "type": "number", "example": 0.06, "nullable": true }, "feePerKwh": { "type": "number", "format": "decimal", "example": 0.07, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0.08, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstKwh" ] }, "description": "Create the price levels according to the kWh.
The first level must have zero value for **firstKwh**.
The last level must have an infinity value for **lastKwh**.
The **fisrtKwh** value on the current level must be equal to the **lastKwh** value on the previous one.
Instead of using a price per kWh there is the option for a flat fee per level. An example of price levels for kWh is given in the table below. | First kWh | Last kWh | Fee per kWh | Flat Fee | | --------- | ------------| ------------|------------ | | 0 | 5.00 | 0.00 | 2.00 | | 5.00 | 10.00 | 0.35 | 0.00 | | 10.00 | null | 0.40 | 0.00 | Applicable for standard tariff." }, "multiPricePerDuration": { "type": "array", "items": { "type": "object", "properties": { "firstUnit": { "type": "integer" }, "lastUnit": { "type": "integer", "example": 1, "nullable": true }, "feePerUnit": { "type": "number", "format": "decimal", "example": 0.05, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstUnit" ] }, "description": "Create the price levels according to the duration of the session from the time the charging started.
The first level must have zero value for **firstUnit**.
The last level must have an infinity value for **lastUnit**.
The **firstUnit** value on the current level must be greater with one unit from the **lastUnit** value on the previous level.
The Unit is created in the **pricePeriodInMinutes** property, the default one is 15 min.
There is the option of applying a flat fee per each level separately.
**Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `multiIdleFee`) will apply during idle periods. An example of price levels for duration is given in the table below. | First Unit | Last Unit | Fee per Unit | Flat Fee | | ----------- | ------------| -------------|------------ | | 0 | 8 | 0.50 | 0.00 | | 9 | 24 | 0.55 | 0.00 | | 25 | null | 0.00 | 10.00 | Applicable for standard tariff." }, "multiIdleFee": { "type": "array", "items": { "type": "object", "properties": { "firstUnit": { "type": "integer" }, "lastUnit": { "type": "integer", "example": 1, "nullable": true }, "feePerUnit": { "type": "number", "format": "decimal", "example": 0.05, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0.06, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstUnit" ] }, "description": "Different price levels could be created depending on the duration of the idle period.
The first level must have zero value for **firstUnit**.
The last level must have an infinity value for **lastUnit**.
The **firstUnit** value on the current level must be greater with one unit from the **lastUnit** value on the previous level.
The Unit is created in the **pricePeriodInMinutes** property, the default one is 15 min.
There is the option of applying a flat fee per each level separately.
Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `multiPricePerDuration`) will be paused. An example of price levels for idle periods is given in the table below. | First Unit | Last Unit | Fee per Unit | Flat Fee | | ----------- | ------------| -------------|------------ | | 0 | 2 | 0.30 | 0.00 | | 3 | 6 | 0.40 | 0.00 | | 7 | null | 0.00 | 0.00 | Applicable for standard tariff." }, "regularUsePeriod": { "type": "number", "nullable": true, "description": "In minutes. Only for the Peak power level tariff." }, "averagePowerLevels": { "type": "array", "items": { "type": "object", "properties": { "averagePowerUpToKw": { "type": "number" }, "pricePerMinute": { "type": "number" } }, "required": [ "averagePowerUpToKw", "pricePerMinute" ], "minItems": 2 } }, "peakPowerLevels": { "type": "array", "items": { "type": "object", "properties": { "peakPowerUpToKw": { "type": "number" }, "regularPricePerMinute": { "type": "number" }, "excessUsePricePerMin": { "type": "number" } }, "required": [ "peakPowerUpToKw", "regularPricePerMinute", "excessUsePricePerMin" ], "minItems": 2 } }, "timePeriods": { "type": "array", "items": { "type": "object", "properties": { "startTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "00:00", "description": "The 24-hour format should be used." }, "endTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "00:00", "description": "The 24-hour format should be used." } }, "required": [ "startTime", "endTime" ], "minItems": 1 } }, "pricePeriods": { "type": "object", "properties": { "connectionFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "energyFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "durationFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Duration fees for each time period. Applicable for standard_tod tariff. **Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `idleFeePeriods`) will apply during idle periods." }, "idleFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Idle fees for each time period. Applicable for standard_tod tariff. Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `durationFeePeriods`) will be paused." } } }, "daysWhenApplied": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "specialDates": { "type": "array", "items": { "type": "string", "format": "date" }, "example": "2022-01-30" }, "idleFeeGracePeriodMinutes": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee grace period (min). Optional. The interpretation of this field depends on `idleFeeGracePeriodMode`: - When mode is `idle_detection` (default): The user is given this grace period after idle state is detected (no charging) to remove the vehicle, before idle fee starts applying. - When mode is `session_start`: This represents the minimum session duration before idle fee applies. Idle fee will not be charged until the session has been active for at least this many minutes." }, "idlePricingPeriodInMinutes": { "type": "number", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging)." }, "connectionFeeMinimumSessionDuration": { "type": "integer", "nullable": true, "description": "Connection Fee Minimum Session Duration (min). Optional." }, "connectionFeeMinimumSessionEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection Fee Minimum Session Energy (kWh). Optional. Up to 5 digits after the decimal point depending on the currency precision." }, "durationFeeGracePeriod": { "type": "integer", "nullable": true, "description": "Duration Fee Grace Period (min). Optional." }, "pricePeriodInMinutes": { "type": "integer", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Charging period. In minutes. It defines the time-period for charging a fee. Example: If you select 15min then the EV-driver will be charged at the start of every 15min of EV-charging. Applicable for duration+energy and duration+energy time of day" }, "pricePeriods": { "type": "object", "properties": { "connectionFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "energyFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "durationFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Duration fees for each time period. Applicable for standard_tod tariff. **Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `idleFeePeriods`) will apply during idle periods." }, "idleFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Idle fees for each time period. Applicable for standard_tod tariff. Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `durationFeePeriods`) will be paused." } }, "minItems": 1 } } }, "description": "When left empty, this means that this is the standard pricing that would be applied in general without taking into consideration the day." }, "thresholdPriceForEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Price for kWh to be considered by Optimised charging for setting the charging periods." }, "priceForEnergyWhenOptimized": { "type": "number", "format": "decimal", "nullable": true }, "optimisedLabel": { "type": "string", "nullable": true }, "durationFeeFrom": { "type": "string", "format": "time", "nullable": true, "description": "Defined start time for the application of duration fees." }, "durationFeeTo": { "type": "string", "format": "time", "nullable": true, "description": "Defined end time for the application of duration fees." }, "subsidyIntegrationId": { "type": "integer", "nullable": true, "description": "**This property is deprecated** Use `subsidy.integrationId` instead. The subsidy integration id that should be applied for this tariff. Only valid for Energy ToU tariffs. Please use the admin panel for the specific integration id. Optional." }, "subsidy": { "type": "object", "properties": { "integrationId": { "type": "integer", "description": "The ID of the subsidy integration that is active on the tariff (or was active when the snapshot was taken)." }, "threshold": { "type": "number", "description": "The energy price threshold (in the operator's currency per kWh) above which the subsidy applies." }, "compensationRate": { "type": "number", "description": "The compensation rate as a percentage (e.g., 90 for 90%)." } }, "required": [ "integrationId", "threshold", "compensationRate" ], "description": "Subsidy parameters for this tariff. Only applicable for Energy ToU tariffs. Omitted when no subsidy is configured." }, "lockPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled the tariff of the charger will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for: - `duration+energy time of day` - it locks duration and energy price components - `energy tou` - it locks energy component only" }, "lockEnergyPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled the tariff of the charger will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for `standard_tod tariff`." }, "lockDurationPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled, the energy fee component of the tariff will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for `standard_tod tariff`." }, "lockIdlePriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled, the duration fee component of the tariff will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the whole duration of their session. Applicable only for `standard_tod tariff`" }, "stateOfChargeIdleThreshold": { "type": "integer", "enum": [ 75, 80, 85, 90, 95, 100 ], "nullable": true, "description": "Switches the session to idle when the SoC (%) exceeds the selected value. Leave empty to use the system wide setting. This option will take effect only if `Allow custom SoC (%) threshold per Tariff` is set in `Idle period detection` setting. This only applies to local charge points, it does not affect sessions on roaming charge points. Leave empty to use the system wide setting." }, "averagePowerIdleThreshold": { "type": "number", "format": "decimal", "minimum": 0, "maximum": 999999.99, "nullable": true, "description": "Sets the session to idle state when the average kW for the past 5 minutes is below the set threshold. This option will take effect only if `Allow custom power threshold per Tariff` is set in `Idle period detection` setting." } } }, "discountTariffSettings": { "type": "object", "properties": { "discountReferenceType": { "type": "string", "enum": [ "base_tariff", "specific_tariff", "roaming_tariff" ], "description": "Determines which tariff the discount is applied to. - `base_tariff` — the discount applies to the base tariff of the tariff group the discount tariff belongs to. - `specific_tariff` — the discount applies to the tariff identified by `referencedTariffId`. - `roaming_tariff` — the discount applies to the CPO wholesale tariff resolved at session time via OCPI. The exact source tariff is unknown at configuration time and varies per CPO partner and per session." }, "referencedTariffId": { "type": "integer", "description": "Present when `discountReferenceType=specific_tariff`. Omitted otherwise. Must reference a non-derived priced tariff owned by the same operator that is not itself `discount based`, `free`, or `charging not allowed`. Submitting a referenced tariff that violates these constraints is rejected with HTTP 422. Compatibility between a `base_tariff` discount and the actual base tariff of the tariff group is enforced when the discount tariff is added to a tariff group, and a `base_tariff` discount applied to a `free` or `charging not allowed` base tariff is rejected with HTTP 422 at that point. Prohibited when `discountReferenceType=roaming_tariff`." }, "discountMode": { "type": "string", "enum": [ "global", "per_element" ], "description": "Determines how the discount is applied. Required when `discountReferenceType` is `base_tariff` or `specific_tariff`. - `global` — a single `discountPercentage` is applied to every fee component of the referenced tariff. - `per_element` — different discount values are applied per fee component, configured via `discountElements`. Prohibited when `discountReferenceType=roaming_tariff` (roaming discounts are always applied globally)." }, "discountPercentage": { "type": "number", "format": "decimal", "minimum": 0, "maximum": 100, "description": "Present when `discountMode=global` and `discountReferenceType` is `base_tariff` or `specific_tariff`. Omitted otherwise. Percentage discount in the range `0` to `100` applied to every fee component of the referenced tariff. Out-of-range values are rejected with HTTP 422. Prohibited when `discountReferenceType=roaming_tariff` (use `discountValue` instead)." }, "discountType": { "type": "string", "enum": [ "percentage", "flat_amount" ], "description": "Present when `discountReferenceType=roaming_tariff`. Prohibited otherwise. - `percentage` — `discountValue` is interpreted as a percentage from 0 to 100. - `flat_amount` — `discountValue` is interpreted as a fixed currency amount to subtract from each CPO price component." }, "discountValue": { "type": "number", "format": "decimal", "minimum": 0, "description": "Present when `discountReferenceType=roaming_tariff`. Prohibited otherwise. The discount value, interpreted according to `discountType`. When `discountType` is `percentage`, the maximum is `100`. When `discountType` is `flat_amount`, the value represents a fixed currency amount with no upper bound." }, "discountElements": { "type": "array", "items": { "type": "object", "properties": { "serviceFeeType": { "type": "string", "enum": [ "flat", "connection", "energy", "charging_time", "idle_time", "min_price", "service_fee" ], "description": "The fee component of the referenced tariff that this discount applies to. Only discount-eligible fee types are accepted." }, "discountType": { "type": "string", "enum": [ "percentage", "flat_amount" ], "description": "- `percentage` — `discountValue` is interpreted as a percentage from 0 to 100. - `flat_amount` — `discountValue` is interpreted as a fixed amount in the operator's currency that is subtracted from the fee component." }, "discountValue": { "type": "number", "format": "decimal", "minimum": 0, "description": "The discount value, interpreted according to `discountType`. When `discountType` is `percentage`, the maximum is 100." } }, "required": [ "serviceFeeType", "discountType", "discountValue" ] }, "description": "Present when `discountMode=per_element` and `discountReferenceType` is `base_tariff` or `specific_tariff`. Omitted otherwise. Each entry configures a discount for a specific fee component of the referenced tariff. At least one entry is required. Prohibited when `discountReferenceType=roaming_tariff`." } }, "description": "Discount configuration for discount based tariffs. Present only when `type=discount based`, omitted otherwise." }, "stopSession": { "type": "object", "properties": { "timeLimitMinutes": { "type": "number", "nullable": true, "description": "Session max time. The maximum minutes a session is allowed to run. Skip for no time limit." }, "stopWhenEnergyExceedsKwh": { "type": "number", "nullable": true, "description": "The maximum energy (kWh) allowed per session. Skip for no limit." }, "stopWhenSocExceedsPercent": { "type": "integer", "minimum": 70, "maximum": 99, "nullable": true, "description": "Stop the session when the vehicle's reported State of Charge reaches or exceeds this value. If the charge point does not report SoC, this criterion is ignored. Accepts values between 70 and 99." } } }, "restrictions": { "type": "object", "properties": { "applyToUsersOfChargePointOwner": { "type": "boolean", "description": "Makes the tariff apply to users of the partner, who is set as owner of the charge point" }, "applyToUsersOfChargePointPartner": { "type": "boolean", "description": "Makes the tariff apply to users of the partner, who is set as owner of the charge point" }, "applyToUsersOfAllRoamingEmsps": { "type": "boolean", "description": "Makes the tariff apply to users of all eMSPs, which are roaming partners" }, "applyToAdHocUsers": { "type": "boolean", "description": "Makes the tariff valid for non-registered users(ad-hoc charging). Mutually exclusive with applyToAdHocOperatorIds." }, "adHocPreAuthorizeAmount": { "type": "number", "minimum": 0, "nullable": true, "description": "Sets the amount that would be blocked on the user's card at the start of the session. Required if applyToAdHocUsers is true or applyToAdHocOperatorIds is non-empty, and one of the following billing strategies is chosen: `Require payment method and authorize certain amount before starting session` or `Require payment method OR minimum amount in balance`." }, "adHocIncrementalPreAuthorizationAmount": { "type": "number", "nullable": true }, "adHocStopWhenPreAuthorizedAmountFallsBelow": { "type": "number", "description": "Set the minimum pre-authorized amount threshold. When the remaining ad hoc pre-authorized amount falls below this value, the charging session will automatically stop to prevent revenue loss." }, "applyToAdHocOperatorIds": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "An array of operator IDs. Makes the tariff apply to registered users from specific operators when charging ad-hoc (cross-operator charging without internal roaming). Mutually exclusive with applyToAdHocUsers." }, "applyToUsersOfPartners": { "type": "array", "items": { "type": "number" }, "description": "Users of specific Partners. Provide a list of partner IDs. Matches if the user is a invited to at least one of the partners." }, "applyToUsersWithGroups": { "type": "array", "items": { "type": "string" }, "description": "Users with a specific group. Provide a list of user groups. Matches if the user is a member of at least one of the groups. Note: Due to improvements in the user groups, this property could be used with some limitations: 1) The value(s) should exactly match the name(s) of the user groups. 2) It would not be possible to create a user group from here anymore. 3) If there are duplicates, the value would not be accepted." }, "applyToHomeChargingOwner": { "type": "boolean", "description": "Makes the tariff apply to the driver who owns the home charge point (the driver, not the partner that manages it)" }, "applyToHomeChargingSharedUsers": { "type": "boolean", "description": "Makes the tariff apply to the drivers the owner has shared the home charge point with (accepted shares only)" }, "applyToUserGroupIds": { "type": "array", "items": { "type": "number" }, "description": "An array of user group IDs. Users with a specific group. Provide a list of user group IDs. This restriction applies if the user is a member of at least one of the groups." }, "applyToUsersWithSubscriptions": { "type": "array", "items": { "type": "number" }, "description": "Users with a specific subscription plan. Provide a list of subscription plan IDs. Matches if the user has active one of the subscription plans." }, "applyToAuthorizationMethods": { "type": "array", "items": { "type": "string", "enum": [ "id_tag", "mac_address", "user_device", "plug_and_charge", "plug_and_charge_iso15118" ] }, "description": "The tariff applies to local users (non-roaming) who authorize using any of the selected methods. When omitted or empty, the tariff applies regardless of authorization method. Values align with the `Authorization.method` property: - `id_tag` - Authorization via physical RFID card - `mac_address` - Authorization via vehicle MAC address (AutoCharge) - `user_device` - Authorization via mobile app or web portal - `plug_and_charge` - Authorization via Plug & Charge protocol - `plug_and_charge_iso15118` - Authorization via ISO15118 Plug & Charge protocol" }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "The date from which the tariff becomes valid." }, "endDate": { "type": "string", "format": "date", "nullable": true, "description": "The expiry date of the tariff. The tariff is valid until this date inclusive." } } }, "partner": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "The assigned Partner will have access to make changes to the tariff." } } }, "display": { "type": "object", "properties": { "defaultPriceInformation": { "type": "string", "maxLength": 150, "nullable": true, "description": "Deprecated: use the tariff group resource to manage this field." }, "defaultPriceInformationOffline": { "type": "string", "maxLength": 150, "nullable": true, "description": "Deprecated: use the tariff group resource to manage this field." }, "priceInformation": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `priceInformationLocalized` instead.** The scalar field only carries the default-locale value and cannot round-trip multi-locale content. The information that would be shown on the display of the charge point for users that are eligible for this tariff." }, "priceInformationLocalized": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "totalCostInformation": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `totalCostInformationLocalized` instead.** The scalar field only carries the default-locale value and cannot round-trip multi-locale content. Additional information that would be displayed on the charge point when the session ends, along with the total fees for energy, duration and idle." }, "totalCostInformationLocalized": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "plainTextModeEnabled": { "type": "boolean", "default": false, "description": "When `true`, the display text is delivered to the charge point without rich text formatting." } } }, "integrationId": { "type": "integer", "nullable": true, "description": "References the internal integration configuration that enables this tariff type" }, "externalId": { "type": "string", "nullable": true, "description": "Used to store custom information, usually used for external references or metadata to the resource." } } } } } }, "responses": { "200": { "description": "Updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariffs/v1.0/{tariff}/scheduled-changes", "method": "GET", "operationId": "tariffScheduledChangesListing", "summary": "Tariff / Scheduled Changes / Listing", "description": "Get all scheduled pricing changes for a tariff", "tags": [ "resource / tariffs" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "failed" ], "example": "pending", "description": "Scheduled tariff pricing change status: - **pending**: Awaiting scheduled time. Can be edited or deleted. - **failed**: Automatic apply errored. Can be viewed or deleted, but not edited." }, "scheduledAfter": { "type": "string", "format": "date-time", "description": "Only changes scheduled at or after this UTC timestamp" }, "scheduledBefore": { "type": "string", "format": "date-time", "description": "Only changes scheduled at or before this UTC timestamp" }, "createdAfter": { "type": "string", "format": "date-time", "description": "Only changes created at or after this UTC timestamp" }, "createdBefore": { "type": "string", "format": "date-time", "description": "Only changes created at or before this UTC timestamp" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariffs/v1.0/{tariff}/scheduled-changes", "method": "POST", "operationId": "tariffScheduledChangeCreate", "summary": "Tariff / Scheduled Change / Create", "description": "Create a new scheduled pricing change for the tariff", "tags": [ "resource / tariffs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledAt": { "type": "string", "format": "date-time", "description": "The UTC date/time when the pricing change takes effect. Must be a future datetime, unique per tariff at minute precision. Seconds and sub-second components are truncated to `:00`." }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "free", "flat rate", "duration+energy", "duration+energy time of day", "energy tou", "standard", "charging not allowed", "average power levels", "peak power levels", "standard_tod", "optimised dynamic pricing" ], "description": "Tariff type" }, "description": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "additionalInformation": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "learnMoreUrl": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "dayTariffStart": { "type": "string", "format": "time", "description": "A time when the day begins" }, "nightTariffStart": { "type": "string", "format": "time", "description": "A time when the night begins" }, "pricing": { "type": "object", "properties": { "pricePerSession": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per session. Only applicable with flat rate tariffs. Up to 5 digits after the decimal point depending on the currency precision." }, "connectionFee": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection fee. A fixed fee that is applied at the start of the charging session. Up to 5 digits after the decimal point depending on the currency precision." }, "pricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh. Up to 5 digits after the decimal point depending on the currency precision." }, "dayPricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision." }, "nightPricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision." }, "pricePeriodInMinutes": { "type": "integer", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Charging period. In minutes. It defines the time-period for charging a fee. Example: If you select 15min then the EV-driver will be charged at the start of every 15min of EV-charging. Applicable for duration+energy and duration+energy time of day" }, "pricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period. Applicable for duration+energy. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`idleFeePerMinute`), the regular duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "durationFeeLimit": { "type": "number", "format": "decimal", "nullable": true, "description": "Duration fee limit for the whole session if fee is applied." }, "durationFeeCapMinutes": { "type": "integer", "nullable": true, "description": "Maximum billable charging duration in minutes. A value of zero means no duration fee is charged. Mutually exclusive with durationFeeLimit." }, "dayPricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`dayIdleFeePerMinute`), the regular day duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "nightPricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`nightIdleFeePerMinute`), the regular night duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "dayIdleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. When configured, this fee applies during idle periods (when no charging is occurring) and replaces the regular day duration fee (`dayPricePerPeriod`). If not configured, the regular day duration fee continues to apply during idle periods." }, "nightIdleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. When configured, this fee applies during idle periods (when no charging is occurring) and replaces the regular night duration fee (`nightPricePerPeriod`). If not configured, the regular night duration fee continues to apply during idle periods." }, "idleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging). Up to 5 digits after the decimal point depending on the currency precision. **For duration+energy tariffs:** When configured, this fee applies during idle periods and replaces the regular duration fee (`pricePerPeriod`). If not configured, the regular duration fee continues to apply during idle periods." }, "idleFeeGracePeriodMinutes": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee grace period (min). Optional. The interpretation of this field depends on `idleFeeGracePeriodMode`: - When mode is `idle_detection` (default): The user is given this grace period after idle state is detected (no charging) to remove the vehicle, before idle fee starts applying. - When mode is `session_start`: This represents the minimum session duration before idle fee applies. Idle fee will not be charged until the session has been active for at least this many minutes." }, "idleFeeGracePeriodMode": { "type": "string", "enum": [ "idle_detection", "session_start" ], "description": "Determines when the idle fee grace period timer starts counting. - `idle_detection` (default): Grace period begins when idle state is detected (vehicle stops charging but remains connected). - `session_start`: Grace period begins from session start time. Idle fee will not apply until the session has been active for at least the grace period duration. Applicable tariff types: `duration+energy`, `duration+energy time of day`, `energy tou`, `standard_tod`." }, "idlePricingPeriodInMinutes": { "type": "number", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging)." }, "idleFeePeriodStart": { "type": "string", "format": "time", "nullable": true, "description": "Defined start time for the application of idle fee." }, "idleFeePeriodEnd": { "type": "string", "format": "time", "nullable": true, "description": "Defined end time for the application of idle fee." }, "idleFeeLimit": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee limit for the whole session if fee is applied." }, "idleFeeCapMinutes": { "type": "integer", "nullable": true, "description": "Maximum billable idle time in minutes. A value of zero means no idle fee is charged. Mutually exclusive with idleFeeLimit." }, "connectionFeeMinimumSessionDuration": { "type": "integer", "nullable": true, "description": "Connection Fee Minimum Session Duration (min). Optional." }, "connectionFeeMinimumSessionEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection Fee Minimum Session Energy (kWh). Optional. Up to 5 digits after the decimal point depending on the currency precision." }, "durationFeeGracePeriod": { "type": "integer", "nullable": true, "description": "Duration Fee Grace Period (min). Optional." }, "minPrice": { "type": "number", "format": "decimal", "nullable": true, "description": "Min. price. Sets a minimum total amount per session. This is helpful in the case your payment service provider has a minimum transaction size or high transaction fees and you want to make sure to have a positive ROI per transaction. Up to 5 digits after the decimal point depending on the currency precision." }, "preAuthorizeAmount": { "type": "number", "format": "decimal", "nullable": true, "description": "Pre-authorize amount. The amount to pre-authorize before starting a session. Up to 5 digits after the decimal point depending on the currency precision." }, "incrementalPreAuthorizationAmount": { "type": "number", "format": "decimal", "description": "The resolved incremental pre-authorization amount for the requesting user context, in the tariff's currency. When the request targets an ad-hoc user (`filter[userId]=null` and the tariff has ad-hoc users enabled), returns the ad-hoc cascade (ad-hoc tariff override → tariff override → global default); otherwise returns the regular cascade (tariff override → global default). Omitted from the response when incremental pre-authorizations are disabled or no amount is configured. On create/update, accept `null` to clear the regular tariff-level override (mirrors `preAuthorizeAmount`); accepted regardless of the global \"Enable incremental pre-authorizations\" setting." }, "taxID": { "type": "integer", "nullable": true, "description": "If Multi-tax Support has been enabled in the platform settings, you can provide the taxId for the tariff here. If you do not provide a value or provide `null`, the Default tax will be used. If Multi-tax Support has not been enabled, any provided value will be ignored." }, "chargePointElectricityRate": { "type": "boolean", "description": "Use the Electricity Rate of the Charge Point that is already attached and aims to track the electricity costs." }, "fallbackElectricityRateId": { "type": "integer", "nullable": true, "description": "When ChargePointElectricityRate is set to *false*, the Electricity Rate ID MUST be supplied in order the electricity rates for the tariff to be known." }, "markupPercentagePerKwh": { "type": "number", "nullable": true }, "markupFixedFeePerKwh": { "type": "number", "nullable": true }, "flexibleMarkUpAsFixedPerKwh": { "type": "object", "properties": { "defaultPrice": { "type": "number", "default": 0, "description": "Set price for the intervals not specified in `intervalPricing` field." }, "intervalPricing": { "type": "array", "items": { "type": "object", "properties": { "startsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The start time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "endsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The end time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "price": { "type": "number", "format": "decimal", "example": 1.23, "description": "The price that will apply for the given price period. Must include tax." } }, "required": [ "startsAt", "endsAt", "price" ], "description": "A specific price period. The `startsAt` and `endsAt` times should be provided in the local time zone and not in UTC. Depending on the tenant multi timezone configuration either the tenant timezone will be used, or the timezone specific to the corresponding resource." }, "description": "Variable-length time periods for markup pricing. Periods can have any duration and do not need to be uniform. Only explicitly configured periods are returned. Time slots not covered by any interval use the `markupFixedFeePerKwh` value. Overlapping intervals are not allowed." } }, "nullable": true, "description": "Set a different fixed markup for different time slots along the day. Applicable for `energy tou` only." }, "multiPricePerKwh": { "type": "array", "items": { "type": "object", "properties": { "firstKwh": { "type": "number", "example": 0.05 }, "lastKwh": { "type": "number", "example": 0.06, "nullable": true }, "feePerKwh": { "type": "number", "format": "decimal", "example": 0.07, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0.08, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstKwh" ] }, "description": "Create the price levels according to the kWh.
The first level must have zero value for **firstKwh**.
The last level must have an infinity value for **lastKwh**.
The **fisrtKwh** value on the current level must be equal to the **lastKwh** value on the previous one.
Instead of using a price per kWh there is the option for a flat fee per level. An example of price levels for kWh is given in the table below. | First kWh | Last kWh | Fee per kWh | Flat Fee | | --------- | ------------| ------------|------------ | | 0 | 5.00 | 0.00 | 2.00 | | 5.00 | 10.00 | 0.35 | 0.00 | | 10.00 | null | 0.40 | 0.00 | Applicable for standard tariff." }, "multiPricePerDuration": { "type": "array", "items": { "type": "object", "properties": { "firstUnit": { "type": "integer" }, "lastUnit": { "type": "integer", "example": 1, "nullable": true }, "feePerUnit": { "type": "number", "format": "decimal", "example": 0.05, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstUnit" ] }, "description": "Create the price levels according to the duration of the session from the time the charging started.
The first level must have zero value for **firstUnit**.
The last level must have an infinity value for **lastUnit**.
The **firstUnit** value on the current level must be greater with one unit from the **lastUnit** value on the previous level.
The Unit is created in the **pricePeriodInMinutes** property, the default one is 15 min.
There is the option of applying a flat fee per each level separately.
**Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `multiIdleFee`) will apply during idle periods. An example of price levels for duration is given in the table below. | First Unit | Last Unit | Fee per Unit | Flat Fee | | ----------- | ------------| -------------|------------ | | 0 | 8 | 0.50 | 0.00 | | 9 | 24 | 0.55 | 0.00 | | 25 | null | 0.00 | 10.00 | Applicable for standard tariff." }, "multiIdleFee": { "type": "array", "items": { "type": "object", "properties": { "firstUnit": { "type": "integer" }, "lastUnit": { "type": "integer", "example": 1, "nullable": true }, "feePerUnit": { "type": "number", "format": "decimal", "example": 0.05, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0.06, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstUnit" ] }, "description": "Different price levels could be created depending on the duration of the idle period.
The first level must have zero value for **firstUnit**.
The last level must have an infinity value for **lastUnit**.
The **firstUnit** value on the current level must be greater with one unit from the **lastUnit** value on the previous level.
The Unit is created in the **pricePeriodInMinutes** property, the default one is 15 min.
There is the option of applying a flat fee per each level separately.
Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `multiPricePerDuration`) will be paused. An example of price levels for idle periods is given in the table below. | First Unit | Last Unit | Fee per Unit | Flat Fee | | ----------- | ------------| -------------|------------ | | 0 | 2 | 0.30 | 0.00 | | 3 | 6 | 0.40 | 0.00 | | 7 | null | 0.00 | 0.00 | Applicable for standard tariff." }, "regularUsePeriod": { "type": "number", "nullable": true, "description": "In minutes. Only for the Peak power level tariff." }, "averagePowerLevels": { "type": "array", "items": { "type": "object", "properties": { "averagePowerUpToKw": { "type": "number" }, "pricePerMinute": { "type": "number" } }, "required": [ "averagePowerUpToKw", "pricePerMinute" ], "minItems": 2 } }, "peakPowerLevels": { "type": "array", "items": { "type": "object", "properties": { "peakPowerUpToKw": { "type": "number" }, "regularPricePerMinute": { "type": "number" }, "excessUsePricePerMin": { "type": "number" } }, "required": [ "peakPowerUpToKw", "regularPricePerMinute", "excessUsePricePerMin" ], "minItems": 2 } }, "timePeriods": { "type": "array", "items": { "type": "object", "properties": { "startTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "00:00", "description": "The 24-hour format should be used." }, "endTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "00:00", "description": "The 24-hour format should be used." } }, "required": [ "startTime", "endTime" ], "minItems": 1 } }, "pricePeriods": { "type": "object", "properties": { "connectionFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "energyFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "durationFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Duration fees for each time period. Applicable for standard_tod tariff. **Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `idleFeePeriods`) will apply during idle periods." }, "idleFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Idle fees for each time period. Applicable for standard_tod tariff. Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `durationFeePeriods`) will be paused." } } }, "daysWhenApplied": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "specialDates": { "type": "array", "items": { "type": "string", "format": "date" }, "example": "2022-01-30" }, "idleFeeGracePeriodMinutes": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee grace period (min). Optional. The interpretation of this field depends on `idleFeeGracePeriodMode`: - When mode is `idle_detection` (default): The user is given this grace period after idle state is detected (no charging) to remove the vehicle, before idle fee starts applying. - When mode is `session_start`: This represents the minimum session duration before idle fee applies. Idle fee will not be charged until the session has been active for at least this many minutes." }, "idlePricingPeriodInMinutes": { "type": "number", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging)." }, "connectionFeeMinimumSessionDuration": { "type": "integer", "nullable": true, "description": "Connection Fee Minimum Session Duration (min). Optional." }, "connectionFeeMinimumSessionEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection Fee Minimum Session Energy (kWh). Optional. Up to 5 digits after the decimal point depending on the currency precision." }, "durationFeeGracePeriod": { "type": "integer", "nullable": true, "description": "Duration Fee Grace Period (min). Optional." }, "pricePeriodInMinutes": { "type": "integer", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Charging period. In minutes. It defines the time-period for charging a fee. Example: If you select 15min then the EV-driver will be charged at the start of every 15min of EV-charging. Applicable for duration+energy and duration+energy time of day" }, "pricePeriods": { "type": "object", "properties": { "connectionFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "energyFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "durationFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Duration fees for each time period. Applicable for standard_tod tariff. **Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `idleFeePeriods`) will apply during idle periods." }, "idleFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Idle fees for each time period. Applicable for standard_tod tariff. Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `durationFeePeriods`) will be paused." } }, "minItems": 1 } } }, "description": "When left empty, this means that this is the standard pricing that would be applied in general without taking into consideration the day." }, "thresholdPriceForEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Price for kWh to be considered by Optimised charging for setting the charging periods." }, "priceForEnergyWhenOptimized": { "type": "number", "format": "decimal", "nullable": true }, "optimisedLabel": { "type": "string", "nullable": true }, "durationFeeFrom": { "type": "string", "format": "time", "nullable": true, "description": "Defined start time for the application of duration fees." }, "durationFeeTo": { "type": "string", "format": "time", "nullable": true, "description": "Defined end time for the application of duration fees." }, "subsidyIntegrationId": { "type": "integer", "nullable": true, "description": "**This property is deprecated** Use `subsidy.integrationId` instead. The subsidy integration id that should be applied for this tariff. Only valid for Energy ToU tariffs. Please use the admin panel for the specific integration id. Optional." }, "subsidy": { "type": "object", "properties": { "integrationId": { "type": "integer", "description": "The ID of the subsidy integration that is active on the tariff (or was active when the snapshot was taken)." }, "threshold": { "type": "number", "description": "The energy price threshold (in the operator's currency per kWh) above which the subsidy applies." }, "compensationRate": { "type": "number", "description": "The compensation rate as a percentage (e.g., 90 for 90%)." } }, "required": [ "integrationId", "threshold", "compensationRate" ], "description": "Subsidy parameters for this tariff. Only applicable for Energy ToU tariffs. Omitted when no subsidy is configured." }, "lockPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled the tariff of the charger will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for: - `duration+energy time of day` - it locks duration and energy price components - `energy tou` - it locks energy component only" }, "lockEnergyPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled the tariff of the charger will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for `standard_tod tariff`." }, "lockDurationPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled, the energy fee component of the tariff will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for `standard_tod tariff`." }, "lockIdlePriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled, the duration fee component of the tariff will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the whole duration of their session. Applicable only for `standard_tod tariff`" }, "stateOfChargeIdleThreshold": { "type": "integer", "enum": [ 75, 80, 85, 90, 95, 100 ], "nullable": true, "description": "Switches the session to idle when the SoC (%) exceeds the selected value. Leave empty to use the system wide setting. This option will take effect only if `Allow custom SoC (%) threshold per Tariff` is set in `Idle period detection` setting. This only applies to local charge points, it does not affect sessions on roaming charge points. Leave empty to use the system wide setting." }, "averagePowerIdleThreshold": { "type": "number", "format": "decimal", "minimum": 0, "maximum": 999999.99, "nullable": true, "description": "Sets the session to idle state when the average kW for the past 5 minutes is below the set threshold. This option will take effect only if `Allow custom power threshold per Tariff` is set in `Idle period detection` setting." } } }, "stopSession": { "type": "object", "properties": { "timeLimitMinutes": { "type": "number", "nullable": true, "description": "Session max time. The maximum minutes a session is allowed to run. Skip for no time limit." }, "stopWhenEnergyExceedsKwh": { "type": "number", "nullable": true, "description": "The maximum energy (kWh) allowed per session. Skip for no limit." }, "stopWhenSocExceedsPercent": { "type": "integer", "minimum": 70, "maximum": 99, "nullable": true, "description": "Stop the session when the vehicle's reported State of Charge reaches or exceeds this value. If the charge point does not report SoC, this criterion is ignored. Accepts values between 70 and 99." } } }, "display": { "type": "object", "properties": { "defaultPriceInformation": { "type": "string", "maxLength": 150, "nullable": true, "description": "Deprecated: use the tariff group resource to manage this field." }, "defaultPriceInformationOffline": { "type": "string", "maxLength": 150, "nullable": true, "description": "Deprecated: use the tariff group resource to manage this field." }, "priceInformation": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `priceInformationLocalized` instead.** The scalar field only carries the default-locale value and cannot round-trip multi-locale content. The information that would be shown on the display of the charge point for users that are eligible for this tariff." }, "priceInformationLocalized": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "totalCostInformation": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `totalCostInformationLocalized` instead.** The scalar field only carries the default-locale value and cannot round-trip multi-locale content. Additional information that would be displayed on the charge point when the session ends, along with the total fees for energy, duration and idle." }, "totalCostInformationLocalized": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "plainTextModeEnabled": { "type": "boolean", "default": false, "description": "When `true`, the display text is delivered to the charge point without rich text formatting." } } } }, "required": [ "scheduledAt" ] } } } }, "responses": { "201": { "description": "Scheduled change created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariffs/v1.0/{tariff}/scheduled-changes/{scheduledChange}", "method": "GET", "operationId": "tariffScheduledChangeRead", "summary": "Tariff / Scheduled Change / Read", "description": "Get a single scheduled pricing change", "tags": [ "resource / tariffs" ], "responses": { "200": { "description": "Scheduled change returned" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariffs/v1.0/{tariff}/scheduled-changes/{scheduledChange}", "method": "DELETE", "operationId": "tariffScheduledChangeDelete", "summary": "Tariff / Scheduled Change / Delete", "description": "Delete a scheduled pricing change", "tags": [ "resource / tariffs" ], "responses": { "204": { "description": "Scheduled change deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tariffs/v1.0/{tariff}/scheduled-changes/{scheduledChange}", "method": "PATCH", "operationId": "tariffScheduledChangeUpdate", "summary": "Tariff / Scheduled Change / Update", "description": "Update a pending scheduled pricing change", "tags": [ "resource / tariffs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledAt": { "type": "string", "format": "date-time", "description": "The UTC date/time when the pricing change takes effect. Must be a future datetime. Seconds and sub-second components are truncated to `:00` (stored at minute precision)." }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "free", "flat rate", "duration+energy", "duration+energy time of day", "energy tou", "standard", "charging not allowed", "average power levels", "peak power levels", "standard_tod", "optimised dynamic pricing" ], "description": "Tariff type. Changing type clears incompatible pricing data." }, "description": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "additionalInformation": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "learnMoreUrl": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "dayTariffStart": { "type": "string", "format": "time", "description": "A time when the day begins" }, "nightTariffStart": { "type": "string", "format": "time", "description": "A time when the night begins" }, "pricing": { "type": "object", "properties": { "pricePerSession": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per session. Only applicable with flat rate tariffs. Up to 5 digits after the decimal point depending on the currency precision." }, "connectionFee": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection fee. A fixed fee that is applied at the start of the charging session. Up to 5 digits after the decimal point depending on the currency precision." }, "pricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh. Up to 5 digits after the decimal point depending on the currency precision." }, "dayPricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision." }, "nightPricePerKwh": { "type": "number", "format": "decimal", "nullable": true, "description": "Price per kWh during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision." }, "pricePeriodInMinutes": { "type": "integer", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Charging period. In minutes. It defines the time-period for charging a fee. Example: If you select 15min then the EV-driver will be charged at the start of every 15min of EV-charging. Applicable for duration+energy and duration+energy time of day" }, "pricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period. Applicable for duration+energy. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`idleFeePerMinute`), the regular duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "durationFeeLimit": { "type": "number", "format": "decimal", "nullable": true, "description": "Duration fee limit for the whole session if fee is applied." }, "durationFeeCapMinutes": { "type": "integer", "nullable": true, "description": "Maximum billable charging duration in minutes. A value of zero means no duration fee is charged. Mutually exclusive with durationFeeLimit." }, "dayPricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`dayIdleFeePerMinute`), the regular day duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "nightPricePerPeriod": { "type": "number", "format": "decimal", "nullable": true, "description": "Charging fee per period during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. **Idle period behavior:** If no idle fee is configured (`nightIdleFeePerMinute`), the regular night duration fee continues to apply during idle periods. When an idle fee is configured, it replaces the duration fee during idle periods." }, "dayIdleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute during the day. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. When configured, this fee applies during idle periods (when no charging is occurring) and replaces the regular day duration fee (`dayPricePerPeriod`). If not configured, the regular day duration fee continues to apply during idle periods." }, "nightIdleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute during the night. Applicable for duration+energy time of day. Up to 5 digits after the decimal point depending on the currency precision. When configured, this fee applies during idle periods (when no charging is occurring) and replaces the regular night duration fee (`nightPricePerPeriod`). If not configured, the regular night duration fee continues to apply during idle periods." }, "idleFeePerMinute": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging). Up to 5 digits after the decimal point depending on the currency precision. **For duration+energy tariffs:** When configured, this fee applies during idle periods and replaces the regular duration fee (`pricePerPeriod`). If not configured, the regular duration fee continues to apply during idle periods." }, "idleFeeGracePeriodMinutes": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee grace period (min). Optional. The interpretation of this field depends on `idleFeeGracePeriodMode`: - When mode is `idle_detection` (default): The user is given this grace period after idle state is detected (no charging) to remove the vehicle, before idle fee starts applying. - When mode is `session_start`: This represents the minimum session duration before idle fee applies. Idle fee will not be charged until the session has been active for at least this many minutes." }, "idleFeeGracePeriodMode": { "type": "string", "enum": [ "idle_detection", "session_start" ], "description": "Determines when the idle fee grace period timer starts counting. - `idle_detection` (default): Grace period begins when idle state is detected (vehicle stops charging but remains connected). - `session_start`: Grace period begins from session start time. Idle fee will not apply until the session has been active for at least the grace period duration. Applicable tariff types: `duration+energy`, `duration+energy time of day`, `energy tou`, `standard_tod`." }, "idlePricingPeriodInMinutes": { "type": "number", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging)." }, "idleFeePeriodStart": { "type": "string", "format": "time", "nullable": true, "description": "Defined start time for the application of idle fee." }, "idleFeePeriodEnd": { "type": "string", "format": "time", "nullable": true, "description": "Defined end time for the application of idle fee." }, "idleFeeLimit": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee limit for the whole session if fee is applied." }, "idleFeeCapMinutes": { "type": "integer", "nullable": true, "description": "Maximum billable idle time in minutes. A value of zero means no idle fee is charged. Mutually exclusive with idleFeeLimit." }, "connectionFeeMinimumSessionDuration": { "type": "integer", "nullable": true, "description": "Connection Fee Minimum Session Duration (min). Optional." }, "connectionFeeMinimumSessionEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection Fee Minimum Session Energy (kWh). Optional. Up to 5 digits after the decimal point depending on the currency precision." }, "durationFeeGracePeriod": { "type": "integer", "nullable": true, "description": "Duration Fee Grace Period (min). Optional." }, "minPrice": { "type": "number", "format": "decimal", "nullable": true, "description": "Min. price. Sets a minimum total amount per session. This is helpful in the case your payment service provider has a minimum transaction size or high transaction fees and you want to make sure to have a positive ROI per transaction. Up to 5 digits after the decimal point depending on the currency precision." }, "preAuthorizeAmount": { "type": "number", "format": "decimal", "nullable": true, "description": "Pre-authorize amount. The amount to pre-authorize before starting a session. Up to 5 digits after the decimal point depending on the currency precision." }, "incrementalPreAuthorizationAmount": { "type": "number", "format": "decimal", "description": "The resolved incremental pre-authorization amount for the requesting user context, in the tariff's currency. When the request targets an ad-hoc user (`filter[userId]=null` and the tariff has ad-hoc users enabled), returns the ad-hoc cascade (ad-hoc tariff override → tariff override → global default); otherwise returns the regular cascade (tariff override → global default). Omitted from the response when incremental pre-authorizations are disabled or no amount is configured. On create/update, accept `null` to clear the regular tariff-level override (mirrors `preAuthorizeAmount`); accepted regardless of the global \"Enable incremental pre-authorizations\" setting." }, "taxID": { "type": "integer", "nullable": true, "description": "If Multi-tax Support has been enabled in the platform settings, you can provide the taxId for the tariff here. If you do not provide a value or provide `null`, the Default tax will be used. If Multi-tax Support has not been enabled, any provided value will be ignored." }, "chargePointElectricityRate": { "type": "boolean", "description": "Use the Electricity Rate of the Charge Point that is already attached and aims to track the electricity costs." }, "fallbackElectricityRateId": { "type": "integer", "nullable": true, "description": "When ChargePointElectricityRate is set to *false*, the Electricity Rate ID MUST be supplied in order the electricity rates for the tariff to be known." }, "markupPercentagePerKwh": { "type": "number", "nullable": true }, "markupFixedFeePerKwh": { "type": "number", "nullable": true }, "flexibleMarkUpAsFixedPerKwh": { "type": "object", "properties": { "defaultPrice": { "type": "number", "default": 0, "description": "Set price for the intervals not specified in `intervalPricing` field." }, "intervalPricing": { "type": "array", "items": { "type": "object", "properties": { "startsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The start time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "endsAt": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "23:45", "description": "The end time of the period. Formatted as hours:minutes. Should be provided in the local time zone and not in UTC. Uses 24-hour notation." }, "price": { "type": "number", "format": "decimal", "example": 1.23, "description": "The price that will apply for the given price period. Must include tax." } }, "required": [ "startsAt", "endsAt", "price" ], "description": "A specific price period. The `startsAt` and `endsAt` times should be provided in the local time zone and not in UTC. Depending on the tenant multi timezone configuration either the tenant timezone will be used, or the timezone specific to the corresponding resource." }, "description": "Variable-length time periods for markup pricing. Periods can have any duration and do not need to be uniform. Only explicitly configured periods are returned. Time slots not covered by any interval use the `markupFixedFeePerKwh` value. Overlapping intervals are not allowed." } }, "nullable": true, "description": "Set a different fixed markup for different time slots along the day. Applicable for `energy tou` only." }, "multiPricePerKwh": { "type": "array", "items": { "type": "object", "properties": { "firstKwh": { "type": "number", "example": 0.05 }, "lastKwh": { "type": "number", "example": 0.06, "nullable": true }, "feePerKwh": { "type": "number", "format": "decimal", "example": 0.07, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0.08, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstKwh" ] }, "description": "Create the price levels according to the kWh.
The first level must have zero value for **firstKwh**.
The last level must have an infinity value for **lastKwh**.
The **fisrtKwh** value on the current level must be equal to the **lastKwh** value on the previous one.
Instead of using a price per kWh there is the option for a flat fee per level. An example of price levels for kWh is given in the table below. | First kWh | Last kWh | Fee per kWh | Flat Fee | | --------- | ------------| ------------|------------ | | 0 | 5.00 | 0.00 | 2.00 | | 5.00 | 10.00 | 0.35 | 0.00 | | 10.00 | null | 0.40 | 0.00 | Applicable for standard tariff." }, "multiPricePerDuration": { "type": "array", "items": { "type": "object", "properties": { "firstUnit": { "type": "integer" }, "lastUnit": { "type": "integer", "example": 1, "nullable": true }, "feePerUnit": { "type": "number", "format": "decimal", "example": 0.05, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstUnit" ] }, "description": "Create the price levels according to the duration of the session from the time the charging started.
The first level must have zero value for **firstUnit**.
The last level must have an infinity value for **lastUnit**.
The **firstUnit** value on the current level must be greater with one unit from the **lastUnit** value on the previous level.
The Unit is created in the **pricePeriodInMinutes** property, the default one is 15 min.
There is the option of applying a flat fee per each level separately.
**Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `multiIdleFee`) will apply during idle periods. An example of price levels for duration is given in the table below. | First Unit | Last Unit | Fee per Unit | Flat Fee | | ----------- | ------------| -------------|------------ | | 0 | 8 | 0.50 | 0.00 | | 9 | 24 | 0.55 | 0.00 | | 25 | null | 0.00 | 10.00 | Applicable for standard tariff." }, "multiIdleFee": { "type": "array", "items": { "type": "object", "properties": { "firstUnit": { "type": "integer" }, "lastUnit": { "type": "integer", "example": 1, "nullable": true }, "feePerUnit": { "type": "number", "format": "decimal", "example": 0.05, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." }, "flatFee": { "type": "number", "format": "decimal", "example": 0.06, "nullable": true, "description": "Up to 5 digits after the decimal point depending on the currency precision." } }, "required": [ "firstUnit" ] }, "description": "Different price levels could be created depending on the duration of the idle period.
The first level must have zero value for **firstUnit**.
The last level must have an infinity value for **lastUnit**.
The **firstUnit** value on the current level must be greater with one unit from the **lastUnit** value on the previous level.
The Unit is created in the **pricePeriodInMinutes** property, the default one is 15 min.
There is the option of applying a flat fee per each level separately.
Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `multiPricePerDuration`) will be paused. An example of price levels for idle periods is given in the table below. | First Unit | Last Unit | Fee per Unit | Flat Fee | | ----------- | ------------| -------------|------------ | | 0 | 2 | 0.30 | 0.00 | | 3 | 6 | 0.40 | 0.00 | | 7 | null | 0.00 | 0.00 | Applicable for standard tariff." }, "regularUsePeriod": { "type": "number", "nullable": true, "description": "In minutes. Only for the Peak power level tariff." }, "averagePowerLevels": { "type": "array", "items": { "type": "object", "properties": { "averagePowerUpToKw": { "type": "number" }, "pricePerMinute": { "type": "number" } }, "required": [ "averagePowerUpToKw", "pricePerMinute" ], "minItems": 2 } }, "peakPowerLevels": { "type": "array", "items": { "type": "object", "properties": { "peakPowerUpToKw": { "type": "number" }, "regularPricePerMinute": { "type": "number" }, "excessUsePricePerMin": { "type": "number" } }, "required": [ "peakPowerUpToKw", "regularPricePerMinute", "excessUsePricePerMin" ], "minItems": 2 } }, "timePeriods": { "type": "array", "items": { "type": "object", "properties": { "startTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "00:00", "description": "The 24-hour format should be used." }, "endTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "example": "00:00", "description": "The 24-hour format should be used." } }, "required": [ "startTime", "endTime" ], "minItems": 1 } }, "pricePeriods": { "type": "object", "properties": { "connectionFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "energyFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "durationFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Duration fees for each time period. Applicable for standard_tod tariff. **Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `idleFeePeriods`) will apply during idle periods." }, "idleFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Idle fees for each time period. Applicable for standard_tod tariff. Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `durationFeePeriods`) will be paused." } } }, "daysWhenApplied": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "specialDates": { "type": "array", "items": { "type": "string", "format": "date" }, "example": "2022-01-30" }, "idleFeeGracePeriodMinutes": { "type": "number", "format": "decimal", "nullable": true, "description": "Idle fee grace period (min). Optional. The interpretation of this field depends on `idleFeeGracePeriodMode`: - When mode is `idle_detection` (default): The user is given this grace period after idle state is detected (no charging) to remove the vehicle, before idle fee starts applying. - When mode is `session_start`: This represents the minimum session duration before idle fee applies. Idle fee will not be charged until the session has been active for at least this many minutes." }, "idlePricingPeriodInMinutes": { "type": "number", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Idle fee per minute. A fee per minute that is applied during idle period (no charging)." }, "connectionFeeMinimumSessionDuration": { "type": "integer", "nullable": true, "description": "Connection Fee Minimum Session Duration (min). Optional." }, "connectionFeeMinimumSessionEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Connection Fee Minimum Session Energy (kWh). Optional. Up to 5 digits after the decimal point depending on the currency precision." }, "durationFeeGracePeriod": { "type": "integer", "nullable": true, "description": "Duration Fee Grace Period (min). Optional." }, "pricePeriodInMinutes": { "type": "integer", "enum": [ 1, 15, 30, 60, 240, 360 ], "nullable": true, "description": "Charging period. In minutes. It defines the time-period for charging a fee. Example: If you select 15min then the EV-driver will be charged at the start of every 15min of EV-charging. Applicable for duration+energy and duration+energy time of day" }, "pricePeriods": { "type": "object", "properties": { "connectionFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "energyFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } } }, "durationFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Duration fees for each time period. Applicable for standard_tod tariff. **Idle period behavior:** Duration fees may be paused during idle periods depending on a system-wide setting (\"Do not apply regular duration fee during idle periods\"). When this setting is enabled (the default), only idle fees (if configured via `idleFeePeriods`) will apply during idle periods." }, "idleFeePeriods": { "type": "object", "properties": { "fee": { "type": "array", "items": { "type": "number" } } }, "description": "Idle fees for each time period. Applicable for standard_tod tariff. Idle fees apply when the system detects that a vehicle is no longer actively charging. When the system-wide \"Do not apply regular duration fee during idle periods\" setting is enabled (the default), only this idle fee will accumulate during idle periods -- the regular duration fee (from `durationFeePeriods`) will be paused." } }, "minItems": 1 } } }, "description": "When left empty, this means that this is the standard pricing that would be applied in general without taking into consideration the day." }, "thresholdPriceForEnergy": { "type": "number", "format": "decimal", "nullable": true, "description": "Price for kWh to be considered by Optimised charging for setting the charging periods." }, "priceForEnergyWhenOptimized": { "type": "number", "format": "decimal", "nullable": true }, "optimisedLabel": { "type": "string", "nullable": true }, "durationFeeFrom": { "type": "string", "format": "time", "nullable": true, "description": "Defined start time for the application of duration fees." }, "durationFeeTo": { "type": "string", "format": "time", "nullable": true, "description": "Defined end time for the application of duration fees." }, "subsidyIntegrationId": { "type": "integer", "nullable": true, "description": "**This property is deprecated** Use `subsidy.integrationId` instead. The subsidy integration id that should be applied for this tariff. Only valid for Energy ToU tariffs. Please use the admin panel for the specific integration id. Optional." }, "subsidy": { "type": "object", "properties": { "integrationId": { "type": "integer", "description": "The ID of the subsidy integration that is active on the tariff (or was active when the snapshot was taken)." }, "threshold": { "type": "number", "description": "The energy price threshold (in the operator's currency per kWh) above which the subsidy applies." }, "compensationRate": { "type": "number", "description": "The compensation rate as a percentage (e.g., 90 for 90%)." } }, "required": [ "integrationId", "threshold", "compensationRate" ], "description": "Subsidy parameters for this tariff. Only applicable for Energy ToU tariffs. Omitted when no subsidy is configured." }, "lockPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled the tariff of the charger will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for: - `duration+energy time of day` - it locks duration and energy price components - `energy tou` - it locks energy component only" }, "lockEnergyPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled the tariff of the charger will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for `standard_tod tariff`." }, "lockDurationPriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled, the energy fee component of the tariff will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the duration of their session. Applicable only for `standard_tod tariff`." }, "lockIdlePriceOnSessionStart": { "type": "boolean", "default": false, "description": "When enabled, the duration fee component of the tariff will be saved using the pricing interval when the user starts the charging session. This ensures that the price for the user will remain constant for the whole duration of their session. Applicable only for `standard_tod tariff`" }, "stateOfChargeIdleThreshold": { "type": "integer", "enum": [ 75, 80, 85, 90, 95, 100 ], "nullable": true, "description": "Switches the session to idle when the SoC (%) exceeds the selected value. Leave empty to use the system wide setting. This option will take effect only if `Allow custom SoC (%) threshold per Tariff` is set in `Idle period detection` setting. This only applies to local charge points, it does not affect sessions on roaming charge points. Leave empty to use the system wide setting." }, "averagePowerIdleThreshold": { "type": "number", "format": "decimal", "minimum": 0, "maximum": 999999.99, "nullable": true, "description": "Sets the session to idle state when the average kW for the past 5 minutes is below the set threshold. This option will take effect only if `Allow custom power threshold per Tariff` is set in `Idle period detection` setting." } } }, "stopSession": { "type": "object", "properties": { "timeLimitMinutes": { "type": "number", "nullable": true, "description": "Session max time. The maximum minutes a session is allowed to run. Skip for no time limit." }, "stopWhenEnergyExceedsKwh": { "type": "number", "nullable": true, "description": "The maximum energy (kWh) allowed per session. Skip for no limit." }, "stopWhenSocExceedsPercent": { "type": "integer", "minimum": 70, "maximum": 99, "nullable": true, "description": "Stop the session when the vehicle's reported State of Charge reaches or exceeds this value. If the charge point does not report SoC, this criterion is ignored. Accepts values between 70 and 99." } } }, "display": { "type": "object", "properties": { "defaultPriceInformation": { "type": "string", "maxLength": 150, "nullable": true, "description": "Deprecated: use the tariff group resource to manage this field." }, "defaultPriceInformationOffline": { "type": "string", "maxLength": 150, "nullable": true, "description": "Deprecated: use the tariff group resource to manage this field." }, "priceInformation": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `priceInformationLocalized` instead.** The scalar field only carries the default-locale value and cannot round-trip multi-locale content. The information that would be shown on the display of the charge point for users that are eligible for this tariff." }, "priceInformationLocalized": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "totalCostInformation": { "type": "string", "nullable": true, "description": "**This property is deprecated. Use `totalCostInformationLocalized` instead.** The scalar field only carries the default-locale value and cannot round-trip multi-locale content. Additional information that would be displayed on the charge point when the session ends, along with the total fees for energy, duration and idle." }, "totalCostInformationLocalized": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "en": "example", "fr": "affaire" }, "nullable": true, "description": "Locales that have been created and are not provided on an update will be deleted. Please provide values in all locales that you wish to keep." }, "plainTextModeEnabled": { "type": "boolean", "default": false, "description": "When `true`, the display text is delivered to the charge point without rich text formatting." } } } } } } } }, "responses": { "200": { "description": "Scheduled change updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tax-identification-numbers/v2.0", "method": "GET", "operationId": "taxIdentificationNumbersListing", "summary": "Tax Identification Numbers / Listing", "description": "Get all Tax Identification Numbers", "tags": [ "resource / tax identification numbers" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tax-identification-numbers/v2.0", "method": "POST", "operationId": "taxIdentificationNumberCreate", "summary": "Tax Identification Number / Create", "description": "Create new Tax Identification Number", "tags": [ "resource / tax identification numbers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tax-identification-numbers/v2.0/{taxIdentificationNumber}", "method": "GET", "operationId": "taxIdentificationNumberRead", "summary": "Tax Identification Number / Read", "description": "Get a Tax Identification Number", "tags": [ "resource / tax identification numbers" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tax-identification-numbers/v2.0/{taxIdentificationNumber}", "method": "DELETE", "operationId": "taxIdentificationNumberDelete", "summary": "Tax Identification Number / Delete", "description": "Delete a Tax Identification Number", "tags": [ "resource / tax identification numbers" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/tax-identification-numbers/v2.0/{taxIdentificationNumber}", "method": "PATCH", "operationId": "taxIdentificationNumberUpdate", "summary": "Tax Identification Number / Update", "description": "Tax Identification Numbers", "tags": [ "resource / tax identification numbers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/taxes/v2.0", "method": "GET", "operationId": "taxesListing", "summary": "Taxes / Listing", "description": "Get all Taxes", "tags": [ "resource / taxes" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/taxes/v2.0", "method": "POST", "operationId": "taxCreate", "summary": "Tax / Create", "description": "Create new Tax", "tags": [ "resource / taxes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "displayName": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "nullable": true }, "percentage": { "type": "number", "format": "decimal" }, "taxIdentificationNumberId": { "type": "integer", "nullable": true } }, "required": [ "name", "percentage" ] } } } }, "responses": { "201": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/taxes/v2.0/{tax}", "method": "GET", "operationId": "taxRead", "summary": "Tax / Read", "description": "Get a Tax", "tags": [ "resource / taxes" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/taxes/v2.0/{tax}", "method": "DELETE", "operationId": "taxDelete", "summary": "Tax / Delete", "description": "Delete a Tax", "tags": [ "resource / taxes" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "409": { "description": "The request could not be completed due to a conflict with the current state of the resource. The operation may succeed if retried." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/taxes/v2.0/{tax}", "method": "PATCH", "operationId": "taxUpdate", "summary": "Tax / Update", "description": "Taxes", "tags": [ "resource / taxes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "displayName": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "nullable": true }, "percentage": { "type": "number", "format": "decimal" }, "taxIdentificationNumberId": { "type": "integer", "nullable": true } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/templates/v1.0", "method": "GET", "operationId": "templatesListing", "summary": "Templates / Listing", "description": "Get all charge points templates", "tags": [ "resource / templates" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/terms-and-policies/v2.0", "method": "GET", "operationId": "termsAndPoliciesListing", "summary": "Terms and policies / Listing", "tags": [ "resource / terms and policies" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "documentId": { "type": "integer" }, "validFrom": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/terms-and-policies/v2.0/{termVersion}", "method": "GET", "operationId": "termsAndPoliciesRead", "summary": "Terms and policies / Read", "tags": [ "resource / terms and policies" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/top-up-packages/v2.0", "method": "GET", "operationId": "topUpPackagesListing", "summary": "Top-Up Packages / Listing", "description": "Get all Top-Up Packages", "tags": [ "resource / top-up packages" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "enabled": { "type": "string", "format": "boolean", "description": "Only list enabled or disabled Top-Up Packages" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "405": { "description": "Feature disabled for the system" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/top-up-packages/v2.0", "method": "POST", "operationId": "topUpPackagCreate", "summary": "Top-Up Package / Create", "description": "Create new Top-Up Package", "tags": [ "resource / top-up packages" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "price": { "type": "number", "format": "decimal" }, "bonus": { "type": "number", "format": "decimal" }, "enabled": { "type": "boolean", "nullable": true, "description": "By default is set to `false`." } }, "required": [ "price", "bonus" ] } } } }, "responses": { "201": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "405": { "description": "Feature disabled for the system" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/top-up-packages/v2.0/{topUpPackage}", "method": "GET", "operationId": "topUpPackageRead", "summary": "Top-Up Package / Read", "description": "Get a Top-Up Package", "tags": [ "resource / top-up packages" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "405": { "description": "Feature disabled for the system" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/top-up-packages/v2.0/{topUpPackage}", "method": "DELETE", "operationId": "topUpPackageDelete", "summary": "Top-Up Package / Delete", "description": "Delete a Top-Up Package", "tags": [ "resource / top-up packages" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "405": { "description": "Feature disabled for the system" } } }, { "path": "/public-api/resources/top-up-packages/v2.0/{topUpPackage}", "method": "PATCH", "operationId": "topUpPackageUpdate", "summary": "Top-Up Package / Update", "description": "Top-Up Packages", "tags": [ "resource / top-up packages" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "price": { "type": "number", "format": "decimal" }, "bonus": { "type": "number", "format": "decimal" }, "enabled": { "type": "boolean", "nullable": true } } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "405": { "description": "Feature disabled for the system" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/transactions/v1.0", "method": "GET", "operationId": "transactionsListing", "summary": "Transactions / Listing", "description": "Get all transactions", "tags": [ "resource / transactions" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the transactions created after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the transactions created before this datetime" }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the transactions that were last updated after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the transactions that were last updated before this datetime" }, "paymentMethod": { "type": "string", "enum": [ "visa", "mastercard", "paypal", "maestro", "amex", "bancontact", "cartes_bancaires", "diners_club", "discover", "interac", "jcb", "mada", "visa_electron", "unknown", "applepay", "googlepay", "twint", "other" ], "description": "Only list transactions by type of payment method. For card-network values, prefer the `filter[cardNetwork]` filter. Wallet-type filtering is available only through this filter." }, "cardNetwork": { "type": "array", "items": { "type": "string", "enum": [ "visa", "mastercard", "paypal", "maestro", "amex", "bancontact", "cartes_bancaires", "diners_club", "discover", "interac", "jcb", "mada", "visa_electron", "unknown" ] }, "description": "Only list transactions by effective card network. For transactions with a linked card payment method, matches the linked payment method card network. For terminal and ad-hoc transactions without a linked card payment method, matches the card network recorded on the transaction. Transactions with no stored card network in the applicable source are excluded. Matches any listed card network. This filter is combined with other filters using AND logic." }, "cardType": { "type": "string", "enum": [ "credit", "debit", "prepaid" ], "description": "Card category. Allowed values: - `credit` - Credit card. - `debit` - Debit card. - `prepaid` - Prepaid card." }, "bin": { "type": "string", "minLength": 6, "maxLength": 8, "pattern": "^\\d{6,8}$", "description": "Only list transactions by bank identification number, using a 6- to 8-digit value. This filter is combined with other filters using AND logic." }, "cardLast4": { "type": "string", "minLength": 4, "maxLength": 4, "pattern": "^\\d{4}$", "description": "Only list transactions matching the exact four digits stored in the card payment snapshot. This filter is combined with other filters using AND logic and applies across the full transaction history without an automatic date limit. Supplying it also removes the implicit 30-day window that `totalAmount` applies on its own." }, "fingerprint": { "type": "string", "description": "Only list transactions by card fingerprint. This filter is combined with other filters using AND logic." }, "acquirerName": { "type": "string", "description": "Only list transactions whose acquiring bank name starts with this prefix. Matching is case-insensitive. This filter is combined with other filters using AND logic." }, "issuerName": { "type": "string", "description": "Only list transactions whose issuing bank name starts with this prefix. Matching is case-insensitive. This filter is combined with other filters using AND logic." }, "issuerCode": { "type": "string", "description": "Only list transactions by issuing bank code. This filter is combined with other filters using AND logic." }, "userId": { "type": "string", "format": "integer", "description": "Only list transactions by a certain user" }, "invoiceNumber": { "type": "string", "description": "Filter transactions by invoice number string (e.g., \"INV-2024-001\"). Use this when you have the human-readable invoice number. To filter by the invoice's database ID, use invoiceId instead." }, "status": { "type": "string", "enum": [ "pending", "finalized", "failed", "reserved", "refunded", "authorized", "initialized" ], "description": "Only list transaction in this status" }, "pendingReason": { "type": "array", "items": { "type": "string", "enum": [ "3ds_authentication", "psp_processing", "bank_transfer_pending", "bank_transfer_processing", "payment_terminal_authorization", "awaiting_reconciliation", "other" ], "example": "3ds_authentication", "description": "Reason a transaction is currently pending. Available only while `status` is `pending`; omitted once the transaction reaches a terminal status. The property may also be absent on a pending transaction when no specific reason has been recorded — for example legacy transactions created before the enum rolled out to all PSPs, or transactions handled by a payment service provider that does not yet report a pending reason. - **3ds_authentication**: Transaction requires 3D Secure verification from the user - **psp_processing**: Payment processor is processing the transaction - **bank_transfer_pending**: User needs to complete the bank transfer redirect - **bank_transfer_processing**: Bank transfer initiated, awaiting confirmation - **payment_terminal_authorization**: Waiting for payment terminal authorization - **awaiting_reconciliation**: The payment is handled by a payment terminal on the charge point, and the transaction is waiting to be reconciled with the amount that terminal settles. The amount currently on the transaction is provisional until reconciliation completes. - **other**: Pending but the reason does not fit any of the defined categories" }, "description": "Only list transactions with the specified pending reason(s). When this filter is applied, results are implicitly limited to transactions whose status is `pending`." }, "sessionId": { "type": "string", "format": "integer", "description": "Only list transaction with this session id" }, "ref": { "type": "string", "description": "Filter transactions by their exact reference value. For partial / substring matching, use refContains." }, "refContains": { "type": "string", "description": "Filter transactions by reference number using partial (substring) matching against the reference field. Matching is case-insensitive (per the database collation). Values shorter than 3 characters are ignored and the filter has no effect. When no createdAfter / createdBefore (or deprecated dateFrom / dateTo) filter is supplied, results are scoped to transactions created within the last 30 days." }, "billingType": { "type": "string", "enum": [ "internal", "external" ], "description": "Only list transactions with the selected billing type." }, "terminalId": { "type": "string", "format": "integer", "description": "Only list transactions with specific payment terminal id." }, "finalizedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the transactions finalized before this datetime. Supplying it also removes the implicit 30-day window that `totalAmount` applies on its own." }, "finalizedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the transactions finalized after this datetime. Supplying it also removes the implicit 30-day window that `totalAmount` applies on its own." }, "totalAmount": { "type": "number", "minimum": 0, "description": "Exact match on the transaction's total amount, in any currency; combined with other filters using AND. When no `cardLast4`, `finalizedAfter`, or `finalizedBefore` is supplied, results are scoped to transactions finalized within the last 30 days." }, "voucherId": { "type": "string", "format": "integer", "description": "Only list transactions paid with this specific voucher id." }, "receiptId": { "type": "string", "format": "integer", "description": "Only list transactions associated with this specific receipt database ID." }, "invoiceId": { "type": "string", "format": "integer", "description": "Filter transactions by invoice's internal database ID as returned in the transaction response. Use this when you have the invoiceId from a previous API response. To filter by the human-readable invoice number string, use invoiceNumber instead." }, "purchaseType": { "type": "array", "items": { "type": "string", "enum": [ "session", "subscription_plan", "topup_package", "custom_fee", "payment_terminal_authorisation", "payment_authorisation", "card_registration" ] }, "description": "Only list transactions with the specified purchase type(s). Determines what the transaction was for based on its associated entity." }, "subscriptionBillingPeriodId": { "type": "string", "format": "integer", "description": "Only list transactions belonging to this subscription billing period. Returns both the settlement payment transaction and all obligation transactions (sessions, base fee, charger fees) for the billing period." }, "settledByTransactionId": { "type": "string", "format": "integer", "description": "Only list transactions that were settled by this specific transaction. Given a settlement transaction ID, returns all obligation transactions (sessions, base fee, charger fees) that were settled by that payment." } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/transactions/v1.0", "method": "POST", "operationId": "transactionsCreate", "summary": "Transactions / Create", "description": "Create new Transaction", "tags": [ "resource / transactions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens when sessionId is not provided. Optional for operator-scoped tokens (defaults to token's operator). Ignored when sessionId is provided (operator is derived from the session)." }, "sessionId": { "type": "integer", "description": "The ID of the charging session to associate with this transaction. Sessions initiated over OCPP (local payment terminal, RFID, plug-and-charge) are eligible, provided the session belongs to the token's operator." }, "paymentMethod": { "type": "object", "properties": { "cardType": { "type": "string", "enum": [ "credit", "debit", "prepaid" ], "description": "Card category. Allowed values: - `credit` - Credit card. - `debit` - Debit card. - `prepaid` - Prepaid card." }, "bin": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Bank identification number recorded for this transaction (first 6-8 digits). A value consisting only of whitespace or invisible characters is rejected." }, "fingerprint": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique card fingerprint recorded for this transaction for cross-channel and cross-PSP card identification. Carries the Payment Account Reference (PAR) where the PSP provides it. A value consisting only of whitespace or invisible characters is rejected." }, "acquirerName": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Name of the acquiring bank recorded for this transaction. A value consisting only of whitespace or invisible characters is rejected." }, "issuerName": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Name of the card issuing bank recorded for this transaction. A value consisting only of whitespace or invisible characters is rejected." }, "issuerCode": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Code of the card issuing bank recorded for this transaction. A value consisting only of whitespace or invisible characters is rejected." }, "methodType": { "type": "string", "enum": [ "card", "bank_transfer", "wallet" ] }, "cardNetwork": { "type": "string", "enum": [ "visa", "mastercard", "paypal", "maestro", "amex", "bancontact", "cartes_bancaires", "diners_club", "discover", "interac", "jcb", "mada", "visa_electron", "unknown" ], "description": "Required when `methodType` is `card`" }, "bankTransferType": { "type": "string", "enum": [ "pse", "sepa" ], "description": "Required when `methodType` is `bank_transfer`" }, "walletType": { "type": "string", "enum": [ "applepay", "googlepay", "twint", "bancontact", "other" ], "description": "Required when `methodType` is `wallet`" }, "type": { "type": "string", "enum": [ "visa", "mastercard", "paypal", "maestro", "amex", "bancontact", "cartes_bancaires", "diners_club", "discover", "interac", "jcb", "mada", "visa_electron", "unknown" ], "description": "Deprecated, please use `methodType` and `cardNetwork` instead." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4 }, "expMonth": { "type": "string" }, "expYear": { "type": "string" } } }, "totalAmount": { "type": "number", "minimum": 0, "maximum": 10000000000000 }, "authorizedAmount": { "type": "number", "minimum": 0, "maximum": 10000000000000, "description": "The PSP-authorised ceiling for this transaction. When omitted, the platform derives the value from the purchasable's pre-authorisation configuration." }, "status": { "type": "string", "enum": [ "pending", "finalized", "failed", "reversed", "refunded", "authorized", "initialized" ] }, "ref": { "type": "string", "description": "Reference to the payment processor or payment terminal where more information about the transaction could be checked. It is the primary reference for the payment and is updated as the payment progresses through authorisation and capture." }, "failureReason": { "type": "string" }, "invoiceRequired": { "type": "boolean", "description": "When set to `true` and the operator has receipt suppression for invoice issuance enabled, the receipt will be suppressed for this transaction. This is intended for terminal transactions where the customer indicates they want an invoice instead of a receipt." }, "email": { "type": "string", "format": "email", "description": "Email address for invoice delivery. Conditionally required based on the Email field configuration in the operator's invoice integration settings: - When set to \"Required\": This field is mandatory when `invoiceDetails` is provided. - When set to \"Optional\": This field is optional; if omitted, the invoice is issued without email notification. - When set to \"Disabled\": This field must not be provided. Only applicable when `invoiceDetails` is provided." }, "locale": { "type": "string", "example": "en", "description": "ISO language code (e.g., \"en\", \"bg\", \"de\", \"pl\") for bilingual invoice generation. When \"Issue bilingual invoices\" is enabled for the operator, the invoice is generated in both the operator's configured invoice language (primary) and this locale (secondary). If not provided, falls back to: user's preferred locale → operator default → tenant default → English. Only applicable when `invoiceDetails` is provided." }, "invoiceDetails": { "type": "object", "properties": { "invoiceType": { "type": "string", "enum": [ "individual", "company" ], "description": "Type of invoice recipient" }, "individualName": { "type": "string", "description": "Full name of the individual (required when invoiceType is \"individual\")" }, "individualPersonalId": { "type": "string", "description": "Personal identification number" }, "individualTaxId": { "type": "string", "description": "Tax identification number for individual" }, "companyName": { "type": "string", "description": "Company name (required when invoiceType is \"company\")" }, "companyRegNo": { "type": "string", "description": "Company registration number" }, "companyTaxId": { "type": "string", "description": "Company tax identification number" }, "companyTaxAdministrationOfficeName": { "type": "string", "description": "Name of the tax administration office" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "city": { "type": "string" }, "postCode": { "type": "string" }, "address": { "type": "string" }, "recipientCode": { "type": "string", "minLength": 7, "maxLength": 7, "pattern": "^[A-Za-z0-9]{7}$", "example": "ABC1234", "description": "Italian SDI recipient code of the buyer. Only collected when the operator uses the Avalara e-invoicing integration with an Italian mandate. Exactly seven alphanumeric characters; lowercase input is accepted and stored uppercased. An Italian company must supply at least one of `recipientCode` and `recipientCertifiedEmail`. Omit the property when there is no value to supply." }, "recipientCertifiedEmail": { "type": "string", "format": "email", "example": "buyer@pec.example.com", "description": "Certified electronic mail (PEC) address of the buyer. Only collected when the operator uses the Avalara e-invoicing integration with an Italian mandate. An Italian company must supply at least one of `recipientCode` and `recipientCertifiedEmail`. Omit the property when there is no value to supply." } }, "required": [ "invoiceType" ], "description": "Invoice details for automatic ad-hoc invoice issuance upon transaction finalization. When provided, the system creates an ad-hoc user with stored invoice details and automatically issues an invoice when the transaction reaches \"finalized\" status. This field cannot be updated via PATCH after creation. The existing issue-invoice endpoint can still be called to override these details before the invoice is issued." }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" }, "paymentMetadata": { "type": "object", "properties": { "applicationIdentifier": { "type": "string", "maxLength": 255, "description": "Application Identifier (AID) from the card chip." }, "terminalIdentifier": { "type": "string", "maxLength": 255, "description": "Terminal ID configured on the payment device." }, "merchantIdentifier": { "type": "string", "maxLength": 255, "description": "Merchant ID assigned by the acquirer." }, "authorisationCode": { "type": "string", "maxLength": 255, "description": "Authorisation code from the issuer/acquirer." }, "acquirerIdentifier": { "type": "string", "maxLength": 255, "description": "Acquirer ID identifying the acquiring bank." }, "cardholderVerificationMethod": { "type": "string", "enum": [ "no_cvm", "signature", "online_pin", "offline_pin", "consumer_device", "online_pin_and_signature", "offline_pin_and_signature" ], "description": "How the cardholder was verified." } }, "description": "Regulatory payment metadata captured from the payment source (terminal or online). All keys are optional; send only the fields known at write time." }, "paymentOrderReference": { "type": "string", "maxLength": 255, "description": "An additional reference for the same payment, written once by whichever system took the payment and not changed as the payment progresses — either issued by the payment provider or supplied to the provider by the merchant. Recorded so the transaction can be reconciled against the provider's own reports. Omit the property when the transaction has no payment order reference." } }, "required": [ "totalAmount", "status" ] } } } }, "responses": { "201": { "description": "Transaction created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/transactions/v1.0/{transaction}", "method": "GET", "operationId": "transactionRead", "summary": "Transaction / Read", "description": "Get a transation", "tags": [ "resource / transactions" ], "parameters": { "path": { "transaction": { "description": "The Transation ID to fetch", "type": "string", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/transactions/v1.0/{transaction}", "method": "PATCH", "operationId": "transactionUpdate", "summary": "Transaction / Update", "description": "Update a non-finalised transaction", "tags": [ "resource / transactions" ], "parameters": { "path": { "transaction": { "description": "The Transation ID to fetch", "type": "string", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "integer", "description": "The ID of the charging session to associate with this transaction. Can only be set if the transaction does not already have a session assigned. Sessions initiated over OCPP (local payment terminal, RFID, plug-and-charge) are eligible, provided the session belongs to the token's operator." }, "paymentMethod": { "type": "object", "properties": { "cardType": { "type": "string", "enum": [ "credit", "debit", "prepaid" ], "nullable": true, "description": "Card category. Allowed values: - `credit` - Credit card. - `debit` - Debit card. - `prepaid` - Prepaid card." }, "bin": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true, "description": "Bank identification number recorded for this transaction (first 6-8 digits). Send a value to replace the stored one, omit the property to keep it, or send `null` to clear it. A value consisting only of whitespace or invisible characters is rejected - use `null` to clear." }, "fingerprint": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true, "description": "Unique card fingerprint recorded for this transaction for cross-channel and cross-PSP card identification. Carries the Payment Account Reference (PAR) where the PSP provides it. Send a value to replace the stored one, omit the property to keep it, or send `null` to clear it. A value consisting only of whitespace or invisible characters is rejected - use `null` to clear." }, "acquirerName": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true, "description": "Name of the acquiring bank recorded for this transaction. Send a value to replace the stored one, omit the property to keep it, or send `null` to clear it. A value consisting only of whitespace or invisible characters is rejected - use `null` to clear." }, "issuerName": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true, "description": "Name of the card issuing bank recorded for this transaction. Send a value to replace the stored one, omit the property to keep it, or send `null` to clear it. A value consisting only of whitespace or invisible characters is rejected - use `null` to clear." }, "issuerCode": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true, "description": "Code of the card issuing bank recorded for this transaction. Send a value to replace the stored one, omit the property to keep it, or send `null` to clear it. A value consisting only of whitespace or invisible characters is rejected - use `null` to clear." }, "methodType": { "type": "string", "enum": [ "card", "bank_transfer" ] }, "cardNetwork": { "type": "string", "enum": [ "visa", "mastercard", "paypal", "maestro", "amex", "bancontact", "cartes_bancaires", "diners_club", "discover", "interac", "jcb", "mada", "visa_electron", "unknown" ], "description": "Required when `methodType` is `card`" }, "bankTransferType": { "type": "string", "enum": [ "pse", "sepa" ], "description": "Required when `methodType` is `bank_transfer`" }, "type": { "type": "string", "enum": [ "visa", "mastercard", "paypal", "maestro", "amex", "bancontact", "cartes_bancaires", "diners_club", "discover", "interac", "jcb", "mada", "visa_electron", "unknown" ], "description": "Deprecated, please use `methodType` and `cardNetwork` instead." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4 }, "expMonth": { "type": "string" }, "expYear": { "type": "string" } }, "description": "Card and payment method details recorded for this transaction. Omitting the whole `paymentMethod` object leaves every stored card value unchanged. When the object is present, each of its properties is applied independently: a property that is present is written, and a property that is absent from the object keeps its stored value." }, "status": { "type": "string", "enum": [ "pending", "finalized", "failed", "reversed", "refunded", "authorized", "initialized" ] }, "totalAmount": { "type": "number", "minimum": 0, "maximum": 10000000000000 }, "authorizedAmount": { "type": "number", "minimum": 0, "maximum": 10000000000000, "description": "The PSP-authorised ceiling for this transaction. This field is only accepted when the transaction is currently in `authorized` status; otherwise the request returns HTTP 422." }, "ref": { "type": "string", "description": "Reference to the payment processor or payment terminal where more information about the transaction could be checked. It is the primary reference for the payment and is updated as the payment progresses through authorisation and capture." }, "failureReason": { "type": "string" }, "invoiceRequired": { "type": "boolean", "description": "When set to `true` and the operator has receipt suppression for invoice issuance enabled, the receipt will be suppressed for this transaction. This is intended for terminal transactions where the customer indicates they want an invoice instead of a receipt." }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" }, "paymentMetadata": { "type": "object", "properties": { "applicationIdentifier": { "type": "string", "maxLength": 255, "description": "Application Identifier (AID) from the card chip." }, "terminalIdentifier": { "type": "string", "maxLength": 255, "description": "Terminal ID configured on the payment device." }, "merchantIdentifier": { "type": "string", "maxLength": 255, "description": "Merchant ID assigned by the acquirer." }, "authorisationCode": { "type": "string", "maxLength": 255, "description": "Authorisation code from the issuer/acquirer." }, "acquirerIdentifier": { "type": "string", "maxLength": 255, "description": "Acquirer ID identifying the acquiring bank." }, "cardholderVerificationMethod": { "type": "string", "enum": [ "no_cvm", "signature", "online_pin", "offline_pin", "consumer_device", "online_pin_and_signature", "offline_pin_and_signature" ], "description": "How the cardholder was verified." } }, "description": "Regulatory payment metadata captured from the payment source (terminal or online). All keys are optional; only the fields present in the request are persisted, fields omitted from the request keep their stored value (partial-PATCH semantics)." } }, "required": [ "status", "totalAmount" ] } } } }, "responses": { "200": { "description": "Transaction updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/user-devices/v1.0", "method": "GET", "operationId": "userDevicesListing", "summary": "User devices / Listing", "description": "Get a list of user devices registered by the mobile app. Devices are created when the mobile app first communicates with the platform. A user can have multiple devices (one per device where they are logged in). The association is removed on logout — the device record persists with no associated user (an \"orphaned\" device). **Operator scoping:** For operator-scoped tokens, only devices currently associated with a user belonging to the token's operator are returned. Orphaned devices are excluded because the operator that registered the device is no longer resolvable after logout. Devices whose associated user has been soft-deleted ARE returned for the operator they belonged to — the soft-deleted-user signal is preserved for fraud-detection workflows. Applying `filter[operatorId]` follows the same rule. Results are paginated using cursor-based pagination. By default they are ordered by device ID descending (newest devices first); use the `sort` parameter to override this order.", "tags": [ "resource / user-devices" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "userId": { "type": "integer", "description": "Filter by the ID of the user currently associated with the device. Returns only devices currently associated with the specified user." }, "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "hasUser": { "type": "boolean", "description": "Filter by association state: - `true` returns only devices currently associated with a user. - `false` returns only orphaned devices (no current user). Omit to return both. Operator-scoped tokens never receive orphaned devices regardless of this filter." }, "deviceIdentifier": { "type": "string", "example": "74a48672034bae7d", "description": "Filter by device identifier. The primary use case is looking up which user (if any) is currently associated with a given device. Matching is **case-insensitive**. Two devices cannot coexist with identifiers that differ only in case, which makes case-insensitive lookup safe for fraud-detection workflows (a fraudster cannot bypass detection by changing the case of the identifier)." } }, "description": "Filters for user devices listing" } }, "sort": { "description": "Sort the result set by a single field. Prefix the field name with `-` for descending order; omit the prefix for ascending order. Supported fields: - `id` — device ID - `createdAt` — creation timestamp - `updatedAt` — last update timestamp Examples: - `?sort=createdAt` — oldest devices first - `?sort=-createdAt` — newest devices first When omitted, results are ordered by device ID descending (newest first).", "schema": { "type": "string", "enum": [ "id", "-id", "createdAt", "-createdAt", "updatedAt", "-updatedAt" ] } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/user-devices/v1.0/{userDevice}", "method": "GET", "operationId": "userDeviceRead", "summary": "User device / Read", "description": "Get a single user device by ID. **Operator scoping:** Operator-scoped tokens can only read devices currently associated with a user belonging to the token's operator. Devices outside this scope — including orphaned devices — return 404 (the existence of the device is not leaked). Devices whose associated user has been soft-deleted ARE returned to operator-scoped tokens when the soft-deleted user belonged to the token's operator.", "tags": [ "resource / user-devices" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/user-groups/v1.0", "method": "GET", "operationId": "userGroupsListing", "summary": "User Groups / Listing", "description": "Get all user groups", "tags": [ "resource / user-groups" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "noPartner": { "type": "string", "format": "boolean", "description": "True returns User Groups that have no Partner associated, false returns User Groups that have a Partner associated." }, "partnerId": { "type": "string", "format": "integer", "description": "User Groups of a specific Partner." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the user groups that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the user groups that were last updated on and before this datetime" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the user group records that were created on and after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the user group records that were created on and before this datetime" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/user-groups/v1.0", "method": "POST", "operationId": "userGroupCreate", "summary": "User Group / Create", "description": "Create new user group.", "tags": [ "resource / user-groups" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "name": { "type": "string" }, "partnerId": { "type": "integer", "nullable": true, "description": "The partnerId can be updated only if there are no users added to the user group" }, "description": { "type": "string", "maxLength": 2000, "nullable": true }, "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "Used to store custom information, usually used for external references or metadata to the resource." }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "User group created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/user-groups/v1.0/{userGroup}", "method": "GET", "operationId": "userGroupRead", "summary": "User Group / Read", "description": "Get an user group", "tags": [ "resource / user-groups" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/user-groups/v1.0/{userGroup}", "method": "DELETE", "operationId": "userGroupDelete", "summary": "User Group / Delete", "description": "Delete a user group", "tags": [ "resource / user-groups" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/user-groups/v1.0/{userGroup}", "method": "PATCH", "operationId": "userGroupUpdate", "summary": "User Group / Update", "description": "Update a user group", "tags": [ "resource / user-groups" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "partnerId": { "type": "integer", "nullable": true, "description": "The partnerId can be updated only if there are no users added to the user group" }, "description": { "type": "string", "maxLength": 2000, "nullable": true }, "externalId": { "type": "string", "maxLength": 255, "nullable": true, "description": "Used to store custom information, usually used for external references or metadata to the resource." }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0", "method": "GET", "operationId": "usersListing", "summary": "Users / Listing", "description": "Get all users", "deprecated": true, "tags": [ "resource / users" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "userGroupId": { "type": "string", "format": "integer", "description": "Only list users that belong to a certain user group" }, "partnerId": { "type": "string", "format": "integer", "description": "Only list users attached to the partner." }, "externalId": { "type": "string", "description": "Only list users with specific external id" }, "email": { "type": "string", "description": "Only list user with specific email" }, "externalAppData": { "type": "string", "example": "filter[externalAppData.property1.property2]=value", "description": "Only list records with specific external application data. You can use a dot notation to search for nested properties. For example, `filter[externalAppData.property1.property2]=value`." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the users that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the users that were last updated on and before this datetime" }, "lastActivityBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the users whose last activity was before the specified date. Users with no recorded activity are excluded." }, "invoiceDetailsLastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only users whose invoice details were last updated on or after this datetime. Users without invoice details or with null invoiceDetailsLastUpdatedAt are excluded." }, "invoiceDetailsLastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only users whose invoice details were last updated on or before this datetime. Users without invoice details or with null invoiceDetailsLastUpdatedAt are excluded." }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only users that were created on and after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only users that were created on and before this datetime" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "partnerInvites", "externalAppData", "invoiceDetails" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0", "method": "POST", "operationId": "userCreate", "summary": "User / Create", "description": "Create new User", "deprecated": true, "tags": [ "resource / users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "email": { "type": "string", "format": "email" }, "emailVerified": { "type": "string", "example": "2022-11-12 12:00:00", "nullable": true, "description": "ISO 8601 formatted date" }, "password": { "type": "string", "minLength": 6 }, "requirePasswordReset": { "type": "boolean", "description": "Sets a requirement for the user to set a new password when they next open the app. After a new password is set, this option resets automatically." }, "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "state": { "type": "string", "nullable": true, "oneOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "For cases when the country is USA." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "For cases when the country is AU." } ], "description": "The field will be considered only if the provided country is `US` or `AU`" }, "city": { "type": "string" }, "post_code": { "type": "string" }, "address": { "type": "string" }, "vehicle_no": { "type": "string" }, "personal_id": { "type": "string" }, "company_name": { "type": "string" }, "locale": { "type": "string", "example": "en-GB", "nullable": true, "description": "The language and regional settings to use in the app. **Only available** if the option to update the user locale has been enabled for the operator." }, "userGroupIds": { "type": "array", "items": { "type": "integer" } }, "externalId": { "type": "string", "nullable": true, "description": "Third party identifier of the user" }, "options": { "type": "object", "properties": { "sessionsAllowed": { "type": "string", "enum": [ "single_session", "multiple_simultaneous_sessions_per_idtag", "simultaneous_use_of_idtags", "multiple_simultaneous_sessions_remotely_and_idtags" ], "description": "Determine the number of sessions a user could start - single or multiple simultaneous sessions, or whether the user could start simultaneous sessions with several Id Tags." } } }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" }, "receiveNewsAndPromotions": { "type": "boolean", "example": false, "description": "Indicates whether the user has opted into receiving news and promotions. To opt in, set this field to 'true'; otherwise, set it to 'false'." }, "skipPreAuthorization": { "type": "boolean", "description": "When enabled, the user can start charging sessions without a pre-authorization hold on their payment method." }, "skipUnpaidSessionCheck": { "type": "boolean", "description": "When enabled, this user can start new sessions even if they have unpaid sessions or unpaid post-paid subscription fees." }, "bankDetails": { "type": "object", "properties": { "bankIban": { "type": "string", "nullable": true, "description": "IBAN of the bank account." }, "bankCode": { "type": "string", "nullable": true, "description": "Bank code assigned by a central bank, a bank supervisory body or a Bankers Association in the country." }, "bankAccountNumber": { "type": "string", "nullable": true, "description": "Bank account number." }, "bankAccountType": { "type": "string", "nullable": true, "description": "Type of the bank account." }, "bankBic": { "type": "string", "nullable": true, "description": "BIC/SWIFT code of the bank." } } }, "externalAppData": { "type": "object", "additionalProperties": true, "example": { "externalCustomerId": "uuid" }, "nullable": true, "description": "The externalAppData field is an object designed to hold additional data related to external integrations. This object can contain the following keys, which are currently supported: - `externalCustomerId`: A string representing the customer ID of the user in an external payment provider integration. This ID is used to link the user's account within the system to their corresponding account in the external payment provider. If no information is available, the externalAppData object will be null.\"" }, "nonce": { "type": "string", "description": "A optional unique string that is used to prevent replay attacks. It's generated by the server, the client should pass it if the user is being created from an external sign up embedded web app and needs to automatically log in the user in the mobile app after creation." } }, "required": [ "email", "password" ] } } } }, "responses": { "201": { "description": "User created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0/{user}", "method": "GET", "operationId": "userRead", "summary": "User / Read", "description": "Get a user", "deprecated": true, "tags": [ "resource / users" ], "parameters": { "query": { "withAmountDue": { "type": "boolean", "default": false } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0/{user}", "method": "DELETE", "operationId": "userDelete", "summary": "User / Delete", "description": "Delete a user", "deprecated": true, "tags": [ "resource / users" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "409": { "description": "Deletion is blocked by the user's current state — the user has an ongoing or unknown-status charging session, a finished session that is not yet billed or paid, a payment or payment method setup in progress, a payment method in a removal cooldown period, or unsettled subscription obligations. Resolve the conflict and retry." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0/{user}", "method": "PATCH", "operationId": "userUpdate", "summary": "User / Update", "description": "Update user", "deprecated": true, "tags": [ "resource / users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "emailVerified": { "type": "string", "example": "2022-11-12 12:00:00", "nullable": true, "description": "ISO 8601 formatted date" }, "password": { "type": "string", "minLength": 6 }, "requirePasswordReset": { "type": "boolean", "description": "Sets a requirement for the user to set a new password when they next open the app. After a new password is set, this option resets automatically." }, "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "state": { "type": "string", "nullable": true, "oneOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "For cases when the country is USA." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "For cases when the country is AU." } ], "description": "The field will be considered only if the provided country is `US` or `AU`" }, "city": { "type": "string" }, "post_code": { "type": "string" }, "address": { "type": "string" }, "vehicle_no": { "type": "string" }, "company_name": { "type": "string", "nullable": true }, "userGroupIds": { "type": "array", "items": { "type": "integer" } }, "externalId": { "type": "string", "nullable": true, "description": "Third party identifier of the user" }, "options": { "type": "object", "properties": { "sessionsAllowed": { "type": "string", "enum": [ "single_session", "multiple_simultaneous_sessions_per_idtag", "simultaneous_use_of_idtags", "multiple_simultaneous_sessions_remotely_and_idtags" ], "description": "Determine the number of sessions a user could start - single or multiple simultaneous sessions, or whether the user could start simultaneous sessions with several Id Tags." } } }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" }, "receiveNewsAndPromotions": { "type": "boolean", "example": true, "description": "Updates the user's preference for receiving news and promotions. To change their preference, update this field to 'true' to opt in, or 'false' to opt out." }, "skipPreAuthorization": { "type": "boolean", "description": "When enabled, the user can start charging sessions without a pre-authorization hold on their payment method." }, "skipUnpaidSessionCheck": { "type": "boolean", "description": "When enabled, this user can start new sessions even if they have unpaid sessions or unpaid post-paid subscription fees." }, "bankDetails": { "type": "object", "properties": { "bankIban": { "type": "string", "nullable": true, "description": "IBAN of the bank account." }, "bankCode": { "type": "string", "nullable": true, "description": "Bank code assigned by a central bank, a bank supervisory body or a Bankers Association in the country." }, "bankAccountNumber": { "type": "string", "nullable": true, "description": "Bank account number." }, "bankAccountType": { "type": "string", "nullable": true, "description": "Type of the bank account." }, "bankBic": { "type": "string", "nullable": true, "description": "BIC/SWIFT code of the bank." } } }, "externalAppData": { "type": "object", "additionalProperties": true, "example": { "externalCustomerId": "uuid" }, "nullable": true, "description": "The externalAppData field is an object designed to hold additional data related to external integrations. This object can contain the following keys, which are currently supported: - `externalCustomerId`: A string representing the customer ID of the user in an external payment provider integration. This ID is used to link the user's account within the system to their corresponding account in the external payment provider. If no information is available, the externalAppData object will be null. It's a part of the response only if request is called with `include.externalAppData` query parameter." } } } } } }, "responses": { "200": { "description": "User updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0/{user}/invoice-details", "method": "GET", "operationId": "invoiceDetailsRead", "summary": "Invoice details / Read", "tags": [ "resource / users" ], "parameters": { "path": { "user": { "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0/{user}/invoice-details", "method": "POST", "operationId": "invoiceDetailsCreateOrUpdate", "summary": "Invoice details / Create or update", "description": "Create or update user invoice details. **Important**: When the operator has \"Always collect Invoice Details\" enabled in their invoice integration settings, the `requireInvoice` field will always be set to `true` regardless of the request payload value. This override ensures regulatory compliance and business policy enforcement. No error is returned when overrides occur as this is intentional behavior.", "tags": [ "resource / users" ], "parameters": { "path": { "user": { "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "requireInvoice": { "type": "boolean", "default": false, "description": "Whether invoice is required for this user. Note: If the operator has 'Always collect Invoice Details' enabled in their invoice integration settings, this field will always be true regardless of the request payload value." }, "invoiceType": { "type": "string", "enum": [ "individual", "company" ], "nullable": true }, "individualName": { "type": "string", "nullable": true }, "individualPersonalId": { "type": "string", "nullable": true }, "individualTaxId": { "type": "string", "nullable": true }, "companyName": { "type": "string", "nullable": true }, "companyRegNo": { "type": "string", "nullable": true }, "companyTaxId": { "type": "string", "nullable": true }, "companyTaxAdministrationOfficeName": { "type": "string", "nullable": true }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "nullable": true }, "region": { "type": "string", "nullable": true, "description": "When country is not in US, AU, CA, UM or RO, you can provide the region" }, "state": { "anyOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "When the country is US." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "When the country is AU." }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" ], "description": "When the country is CA." }, { "type": "string", "enum": [ "81", "84", "85", "67", "89", "71", "76", "95", "79" ], "description": "When the country is UM." }, { "type": "string", "enum": [ "AB", "AR", "AG", "BC", "BH", "BN", "BT", "BV", "BR", "B", "BZ", "CL", "CS", "CT", "CV", "DB", "DJ", "GL", "GR", "GJ", "HR", "HD", "IL", "IS", "IF", "MM", "MH", "MS", "NT", "OT", "PH", "SM", "SJ", "SB", "SV", "TR", "TM", "TL", "VS", "VL", "VN" ], "description": "When the country is RO." } ], "description": "When the selected country is one of US, AU, CA, UM or RO" }, "city": { "type": "string", "nullable": true }, "postCode": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true } }, "required": [ "requireInvoice", "invoiceType" ], "description": "Built-in invoice processor" }, { "type": "object", "properties": { "invoiceRequired": { "type": "boolean", "default": false }, "clientType": { "type": "string", "enum": [ "individual", "company" ], "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "mobilePhoneNumber": { "type": "string", "nullable": true }, "landlinePhoneNumber": { "type": "string", "nullable": true }, "taxId": { "type": "string", "nullable": true }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "nullable": true }, "city": { "type": "string", "nullable": true }, "postcode": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true } }, "required": [ "invoiceRequired", "clientType" ], "description": "Invoice processor - Cardcom" }, { "type": "object", "properties": { "firstName": { "type": "string", "nullable": false }, "lastName": { "type": "string", "nullable": false }, "email": { "type": "string", "nullable": false }, "phone": { "type": "string", "nullable": true }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "nullable": true }, "city": { "type": "string", "nullable": true }, "postcode": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true } }, "required": [ "firstName", "lastName", "email" ], "description": "Invoice processor - SoftOne" }, { "type": "object", "properties": { "invoiceType": { "type": "string", "enum": [ "EInvoice", "Company", "Donation" ] }, "carrierType": { "type": "string", "enum": [ "Mobile", "Citizen", "GreenWorld" ], "nullable": true }, "loveCode": { "type": "string", "nullable": true, "description": "Donation love code. Required when invoiceType is Donation." }, "mobileBarCode": { "type": "string", "nullable": true, "description": "Mobile carrier barcode. Required when invoiceType is EInvoice and carrierType is Mobile." }, "citizenId": { "type": "string", "nullable": true, "description": "Citizen digital certificate ID. Required when invoiceType is EInvoice and carrierType is Citizen." }, "companyId": { "type": "string", "nullable": true, "description": "Company unified business number. Required when invoiceType is Company." }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "nullable": true }, "city": { "type": "string", "nullable": true }, "postcode": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true } }, "required": [ "invoiceType", "name", "email", "phone" ], "description": "Invoice processor - Ecpay" }, { "type": "object", "properties": { "recipientCode": { "type": "string", "minLength": 7, "maxLength": 7, "pattern": "^[A-Za-z0-9]{7}$", "example": "ABC1234", "nullable": true, "description": "Italian SDI recipient code of the buyer. Only collected when the operator uses the Avalara e-invoicing integration with an Italian mandate. Exactly seven alphanumeric characters; lowercase input is accepted and stored uppercased. An Italian company must supply at least one of `recipientCode` and `recipientCertifiedEmail`. Submit `null` to clear a stored value. Clearing is rejected with a validation error when the operator configures this field as required and the request stores invoice details as required — supply the other identifier instead." }, "recipientCertifiedEmail": { "type": "string", "format": "email", "example": "buyer@pec.example.com", "nullable": true, "description": "Certified electronic mail (PEC) address of the buyer. Only collected when the operator uses the Avalara e-invoicing integration with an Italian mandate. An Italian company must supply at least one of `recipientCode` and `recipientCertifiedEmail`. Submit `null` to clear a stored value. Clearing is rejected with a validation error when the operator configures this field as required and the request stores invoice details as required — supply the other identifier instead." }, "requireInvoice": { "type": "boolean", "default": false, "description": "Whether invoice is required for this user. Note: If the operator has 'Always collect Invoice Details' enabled in their invoice integration settings, this field will always be true regardless of the request payload value." }, "invoiceType": { "type": "string", "enum": [ "individual", "company" ], "nullable": true }, "individualName": { "type": "string", "nullable": true }, "individualPersonalId": { "type": "string", "nullable": true }, "individualTaxId": { "type": "string", "nullable": true }, "companyName": { "type": "string", "nullable": true }, "companyRegNo": { "type": "string", "nullable": true }, "companyTaxId": { "type": "string", "nullable": true }, "companyTaxAdministrationOfficeName": { "type": "string", "nullable": true }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "nullable": true }, "region": { "type": "string", "nullable": true, "description": "When country is not in US, AU, CA, UM or RO, you can provide the region" }, "state": { "anyOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "When the country is US." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "When the country is AU." }, { "type": "string", "enum": [ "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" ], "description": "When the country is CA." }, { "type": "string", "enum": [ "81", "84", "85", "67", "89", "71", "76", "95", "79" ], "description": "When the country is UM." }, { "type": "string", "enum": [ "AB", "AR", "AG", "BC", "BH", "BN", "BT", "BV", "BR", "B", "BZ", "CL", "CS", "CT", "CV", "DB", "DJ", "GL", "GR", "GJ", "HR", "HD", "IL", "IS", "IF", "MM", "MH", "MS", "NT", "OT", "PH", "SM", "SJ", "SB", "SV", "TR", "TM", "TL", "VS", "VL", "VN" ], "description": "When the country is RO." } ], "description": "When the selected country is one of US, AU, CA, UM or RO" }, "city": { "type": "string", "nullable": true }, "postCode": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true } }, "required": [ "requireInvoice", "invoiceType" ], "description": "Avalara e-invoicing processor. Carries the same fields as the platform's native invoice integration, plus the two Italian SDI buyer identifiers. Those two are only collected when the operator's Avalara integration has an Italian mandate, and only stored for company customers. When both identifiers are collected and enabled, an Italian company (`invoiceType` is `company` and `country` is `IT`) must supply at least one of `recipientCode` and `recipientCertifiedEmail`. This either-or requirement is conditional on the invoice type and the country, so it cannot be expressed per field in this schema — a request that omits both is rejected with a validation error reported on both properties." } ] } } } }, "responses": { "200": { "description": "Invoice details created or updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0/{user}/payment-methods", "method": "GET", "operationId": "paymentMethodsListing", "summary": "Payment Methods / Listing", "description": "Get all payment methods for a user", "tags": [ "resource / users" ], "parameters": { "path": { "user": { "type": "integer", "required": true } }, "query": { "page": { "description": "The page number to fetch (defaults to 1)", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0/{user}/payment-methods", "method": "POST", "operationId": "paymentMethodCreate", "summary": "Payment Method / Create", "description": "Initiate a new payment method registration, or finalize it. Note that this is a two step process! # For payment processors with web view integration You will need to initiate a call with no parameters to this endpoint to get a new request to add payment method (Step 1). Then you will have to redirect to an endpoint and wait for the client to enter his credit card details there. Once he/she is done (and reaches the successURL) you must then issue another call to this endpoint with the transactionID that was returned from the first call to finalize the process and retrieve the newly added payment method data (Step 2). ## Step 1 POST with request body, containing `tokenizedType` to determine the type of the method and `bankTransferType` if applicable. This will create a new request to the payment processor for adding a new payment method. As response you will get the `transactionId` to track the payment method registration process, the `redirectUrl` and `successUrl`, to redirect your user to, along with any other attributes that the payment processor requires for tracking. Just pass those additional parameters to Step 2. ### Example request for tokenizedType = card Request: ```json { \"tokenizedType\": \"card\" } ``` ### Example request for tokenizedType = bank_transfer Request: ```json { \"tokenizedType\": \"bank_transfer\", \"bankTransferType\": \"sepa\" } ``` Response: ```json { \"transactionId\": 1234, \"successUrl\": \"http://example.com/payment-processor/success\", \"redirectUrl\": \"http://example.com/payment-processor/web-form/123abc\", \"additionalProcessorArguments\": \"just pass them all top the step 2\" } ``` ## Step 2 POST with request body, containing the `transactionId` along with any other attributes, that were in the response of Step 1 (other then the `transactionId`, `successUrl` and `redirectUrl`). This will finalize the payment method registration and will retrieve the newly added payment method for you. Note that you can also receive the payment methods using the payment methods listing endpoints. The finalized payment method is returned in a `data` wrapper. Depending on the payment processor, the status is `200` or `201`; the body is the same in both cases. The optional `token` and `registrationTransactionId` properties are omitted when they are not set rather than returned as `null`; the card example includes both properties, while the bank transfer example omits `registrationTransactionId`. ### Example Request: ```json { \"transactionId\": 1234, \"successUrl\": \"http://example.com/payment-processor/success\", \"redirectUrl\": \"http://example.com/payment-processor/web-form/123abc\", \"additionalProcessorArguments\": \"just pass them all top the step 2\" } ``` Response: see the `Step 2 - card payment method` and `Step 2 - bank transfer payment method` response examples. # For payment processors with in-app integration Braintree and Stripe integrations DO NOT count out `redirectUrl` as these processors should have an ip-app integration and therefore the app itself should use the appropriate SDK to complete the credit-card tokenization process with the processor. ## Braintree The first step is not required for braintree as the full integration is done in-app. Step 2 needs to pass the `paymentMethodNonce` so that it can be exchanged for the payment method token. ### Example Step 2 Request: ```json {\"paymentMethodNonce\": \"abc123\"} ``` Response: see the `Step 2 - card payment method` and `Step 2 - bank transfer payment method` response examples. ## Stripe Step 1 with stripe will initialize a setup intent, that your app should complete. You will get the details you need in order to do that from the response of that call. Call step 2 once you have completed the setup intent. ### Example Step 1 - when tokenizing card ```json { \"tokenizedType\": \"card\" } ``` ### Example Step 1 - when tokenizing bank transfer Request: ```json { \"tokenizedType\": \"bank_transfer\", \"bankTransferType\": \"sepa\" } ``` Response: ```json { \"publishableKey\": \"345678986543\", \"clientSecret\": \"jyt37hgsv63\", \"setupIntentReference\": \"1234ABC\" } ``` ### Example Step 2 Request: ```json { \"publishableKey\": \"345678986543\", \"clientSecret\": \"jyt37hgsv63\", \"setupIntentReference\": \"1234ABC\" } ``` Response: see the `Step 2 - card payment method` and `Step 2 - bank transfer payment method` response examples.", "tags": [ "resource / users" ], "parameters": { "path": { "user": { "type": "integer", "required": true } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tokenizedType": { "type": "string", "enum": [ "card", "bank_transfer" ], "description": "The type of the tokenized payment method. If not provided - defaults to card" }, "bankTransferType": { "type": "string", "enum": [ "sepa" ], "description": "The type of the bank transfer. Required if `tokenizedType` is `bank_transfer`" }, "transactionId": { "type": "number", "nullable": true, "description": "The ID of the Transaction object, created when you initiated the request." } } }, "examples": { "EmptyBody": { "summary": "Step 1 - all payment methods, defaults to card tokenizedType" }, "CardBody": { "summary": "Step 1 - all payment methods, card tokenizedType", "value": { "tokenizedType": "card" } }, "BankTransferBody": { "summary": "Step 1 - all payment methods, bank_transfer tokenizedType", "value": { "tokenizedType": "bank_transfer", "bankTransferType": "sepa" } }, "FinishStripe": { "summary": "Step 2 - Stripe", "value": { "publishableKey": 345678986543, "clientSecret": "jyt37hgsv63", "setupIntentReference": "1234ABC" } }, "FinishBraintree": { "summary": "Step 2 - Braintree", "value": { "paymentMethodNonce": "asdh266" } }, "Finish": { "summary": "Step 2 - other processors", "value": { "transactionId": 12, "additionalProcessorArguments": "just pass them all top the step 2" } } } } } }, "responses": { "200": { "description": "Request succeeded. Step 1 returns one of the shapes below. Depending on the payment processor, step 2 may also return `200` with the finalized payment method body documented under the `201` response." }, "201": { "description": "The registration created a new payment method. The finalized payment method is returned in a `data` wrapper." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid or problem with processing the request has occurred" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0/{user}/payment-methods/{paymentMethodId}", "method": "GET", "operationId": "paymentMethodRead", "summary": "Payment Method / Read", "description": "Get information for a payment method by ID", "tags": [ "resource / users" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0/{user}/payment-methods/{paymentMethodId}", "method": "DELETE", "operationId": "paymentMethodDelete", "summary": "Payment Method / Delete", "description": "Delete Payment method. Please note that `balance` and `corporate` payment methods CANNOT be removed from this interface", "tags": [ "resource / users" ], "responses": { "204": { "description": "Payment method deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0/{user}/payment-methods/{paymentMethodId}", "method": "PATCH", "operationId": "paymentMethodUpdate", "summary": "Payment Method / Update", "description": "Update Payment method. Please note that `balance` and `corporate` payment methods CANNOT be set as default", "tags": [ "resource / users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "default": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Payment method updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0/{user}/subscription-billing-periods", "method": "GET", "operationId": "subscriptionBillingPeriodsListing", "summary": "Subscription billing periods / Listing", "description": "Get all subscription billing periods for a user", "tags": [ "resource / users" ], "parameters": { "path": { "user": { "type": "integer", "required": true } }, "query": { "filter": { "schema": { "type": "object", "properties": { "subscriptionPlanId": { "type": "string", "format": "integer", "description": "Filter by subscription plan ID" }, "subscriptionId": { "type": "string", "format": "integer", "description": "Filter by subscription ID" }, "hasUnresolvedPaymentFailure": { "type": "string", "format": "boolean", "description": "When `true`, return only billing periods that currently have an unresolved payment failure (`firstPaymentFailureAt` is set). When `false`, return only billing periods without a current failure. Payment failure dates are cleared when a retry succeeds, so this reflects the current failure state, not historical failures." }, "startedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only billing periods started after this datetime." }, "startedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only billing periods started before this datetime." }, "endedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only billing periods ended after this datetime." }, "endedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only billing periods ended before this datetime." } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "405": { "description": "Feature disabled for the system" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.0/{user}/subscription-billing-periods/{billingPeriod}", "method": "GET", "operationId": "subscriptionBillingPeriodRead", "summary": "Subscription billing period / Read", "description": "Get information for a subscription billing period by ID", "tags": [ "resource / users" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "405": { "description": "Feature disabled for the system" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.1", "method": "GET", "operationId": "usersListingV1_1", "summary": "Users / Listing", "description": "Get all users", "tags": [ "resource / users" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "userGroupId": { "type": "string", "format": "integer", "description": "Only list users that belong to a certain user group" }, "partnerId": { "type": "string", "format": "integer", "description": "Only list users attached to the partner." }, "externalId": { "type": "string", "description": "Only list users with specific external id" }, "email": { "type": "string", "description": "Only list user with specific email" }, "externalAppData": { "type": "string", "example": "filter[externalAppData.property1.property2]=value", "description": "Only list records with specific external application data. You can use a dot notation to search for nested properties. For example, `filter[externalAppData.property1.property2]=value`." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the users that were last updated on and after this datetime" }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the users that were last updated on and before this datetime" }, "lastActivityBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the users whose last activity was before the specified date. Users with no recorded activity are excluded." }, "invoiceDetailsLastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only users whose invoice details were last updated on or after this datetime. Users without invoice details or with null invoiceDetailsLastUpdatedAt are excluded." }, "invoiceDetailsLastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only users whose invoice details were last updated on or before this datetime. Users without invoice details or with null invoiceDetailsLastUpdatedAt are excluded." }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only users that were created on and after this datetime" }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only users that were created on and before this datetime" } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" }, "include": { "schema": { "type": "array", "items": { "type": "string", "enum": [ "partnerInvites", "externalAppData", "invoiceDetails" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.1", "method": "POST", "operationId": "userCreateV1_1", "summary": "User / Create", "description": "Create new User", "tags": [ "resource / users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "email": { "type": "string", "format": "email" }, "emailVerified": { "type": "string", "example": "2022-11-12 12:00:00", "nullable": true, "description": "ISO 8601 formatted date" }, "password": { "type": "string", "minLength": 6 }, "requirePasswordReset": { "type": "boolean", "description": "Sets a requirement for the user to set a new password when they next open the app. After a new password is set, this option resets automatically." }, "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "state": { "type": "string", "nullable": true, "oneOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "For cases when the country is USA." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "For cases when the country is AU." } ], "description": "The field will be considered only if the provided country is `US` or `AU`" }, "city": { "type": "string" }, "post_code": { "type": "string" }, "address": { "type": "string" }, "vehicle_no": { "type": "string" }, "personal_id": { "type": "string" }, "company_name": { "type": "string" }, "company_tax_id": { "type": "string" }, "company_address": { "type": "string" }, "company_city": { "type": "string" }, "company_postal_code": { "type": "string" }, "company_country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "company_receipts_enabled": { "type": "boolean", "description": "When enabled, receipt integrations that support company receipts use this user's company details for receipts when all required company fields are present." }, "locale": { "type": "string", "enum": [ "en", "bg", "mk", "el", "zh-CN", "zh-HK", "zh-TW", "pt", "sl", "hr", "it", "de", "hu", "fi", "is", "sv-SE", "da-DK", "nb-NO", "tr-TR", "es-ES", "ar", "ary", "he", "ta", "ms", "cy", "sr", "fr", "fr-MA", "ro", "lt", "uk", "ru", "nl", "ca-ES", "id", "ar-EG", "pl", "lo", "th", "sq-XK", "ga-IE", "bs", "ja", "ko-KR", "cs", "lv", "et", "az", "ka" ], "example": "en", "nullable": true, "description": "The user locale value sets the Mobile App and notifications language. To change this value you must enable 'Allow updating user locale via API' in the EV drivers tab of the Operator resource." }, "userGroupIds": { "type": "array", "items": { "type": "integer" } }, "externalId": { "type": "string", "nullable": true, "description": "Third party identifier of the user" }, "options": { "type": "object", "properties": { "sessionsAllowed": { "type": "string", "enum": [ "single_session", "multiple_simultaneous_sessions_per_idtag", "simultaneous_use_of_idtags", "multiple_simultaneous_sessions_remotely_and_idtags" ], "description": "Determine the number of sessions a user could start - single or multiple simultaneous sessions, or whether the user could start simultaneous sessions with several Id Tags." } } }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" }, "receiveNewsAndPromotions": { "type": "boolean", "example": false, "description": "Indicates whether the user has opted into receiving news and promotions. To opt in, set this field to 'true'; otherwise, set it to 'false'." }, "bankDetails": { "type": "object", "properties": { "bankIban": { "type": "string", "nullable": true, "description": "IBAN of the bank account." }, "bankCode": { "type": "string", "nullable": true, "description": "Bank code assigned by a central bank, a bank supervisory body or a Bankers Association in the country." }, "bankAccountNumber": { "type": "string", "nullable": true, "description": "Bank account number." }, "bankAccountType": { "type": "string", "nullable": true, "description": "Type of the bank account." }, "bankBic": { "type": "string", "nullable": true, "description": "BIC/SWIFT code of the bank." } } }, "externalAppData": { "type": "object", "additionalProperties": true, "example": { "externalCustomerId": "uuid" }, "nullable": true, "description": "The externalAppData field is an object designed to hold additional data related to external integrations. This object can contain the following keys, which are currently supported: - `externalCustomerId`: A string representing the customer ID of the user in an external payment provider integration. This ID is used to link the user's account within the system to their corresponding account in the external payment provider. If no information is available, the externalAppData object will be null.\"" }, "nonce": { "type": "string", "description": "A optional unique string that is used to prevent replay attacks. It's generated by the server, the client should pass it if the user is being created from an external sign up embedded web app and needs to automatically log in the user in the mobile app after creation." }, "partnerId": { "type": "integer", "nullable": true, "description": "The ID of the partner to associate the created user with. When specified, the user will be created with `created_by_partner_id` set and an auto-accepted partner invite. - Required for sub-operator admins (must be a partner belonging to the sub-operator with `allow_partner_to_create_users` enabled). - Optional for operator admins (must belong to the operator's partners) and global admins. - Ignored for partner admins (their own partner is used automatically)." } }, "required": [ "email", "password" ] } } } }, "responses": { "201": { "description": "User created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.1/{user}", "method": "GET", "operationId": "userReadV1_1", "summary": "User / Read", "description": "Get a user", "tags": [ "resource / users" ], "parameters": { "query": { "withAmountDue": { "type": "boolean", "default": false } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.1/{user}", "method": "DELETE", "operationId": "userDeleteV1_1", "summary": "User / Delete", "description": "Delete a user", "tags": [ "resource / users" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "409": { "description": "Deletion is blocked by the user's current state — the user has an ongoing or unknown-status charging session, a finished session that is not yet billed or paid, a payment or payment method setup in progress, a payment method in a removal cooldown period, or unsettled subscription obligations. Resolve the conflict and retry." }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.1/{user}", "method": "PATCH", "operationId": "userUpdateV1_1", "summary": "User / Update", "description": "Update user", "tags": [ "resource / users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "emailVerified": { "type": "string", "example": "2022-11-12 12:00:00", "nullable": true, "description": "ISO 8601 formatted date" }, "password": { "type": "string", "minLength": 6 }, "requirePasswordReset": { "type": "boolean", "description": "Sets a requirement for the user to set a new password when they next open the app. After a new password is set, this option resets automatically." }, "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ] }, "state": { "type": "string", "nullable": true, "oneOf": [ { "type": "string", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ], "description": "For cases when the country is USA." }, { "type": "string", "enum": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT", "JBT", "CX", "NF", "CC", "AQ", "CSI", "ACI", "HM" ], "description": "For cases when the country is AU." } ], "description": "The field will be considered only if the provided country is `US` or `AU`" }, "city": { "type": "string" }, "post_code": { "type": "string" }, "address": { "type": "string" }, "vehicle_no": { "type": "string" }, "personal_id": { "type": "string" }, "company_name": { "type": "string", "nullable": true }, "company_tax_id": { "type": "string", "nullable": true }, "company_address": { "type": "string", "nullable": true }, "company_city": { "type": "string", "nullable": true }, "company_postal_code": { "type": "string", "nullable": true }, "company_country": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "nullable": true }, "company_receipts_enabled": { "type": "boolean", "description": "When enabled, receipt integrations that support company receipts use this user's company details for receipts when all required company fields are present." }, "locale": { "type": "string", "enum": [ "en", "bg", "mk", "el", "zh-CN", "zh-HK", "zh-TW", "pt", "sl", "hr", "it", "de", "hu", "fi", "is", "sv-SE", "da-DK", "nb-NO", "tr-TR", "es-ES", "ar", "ary", "he", "ta", "ms", "cy", "sr", "fr", "fr-MA", "ro", "lt", "uk", "ru", "nl", "ca-ES", "id", "ar-EG", "pl", "lo", "th", "sq-XK", "ga-IE", "bs", "ja", "ko-KR", "cs", "lv", "et", "az", "ka" ], "example": "en", "nullable": true, "description": "The user locale value sets the Mobile App and notifications language. To change this value you must enable 'Allow updating user locale via API' in the EV drivers tab of the Operator resource." }, "userGroupIds": { "type": "array", "items": { "type": "integer" } }, "externalId": { "type": "string", "nullable": true, "description": "Third party identifier of the user" }, "options": { "type": "object", "properties": { "sessionsAllowed": { "type": "string", "enum": [ "single_session", "multiple_simultaneous_sessions_per_idtag", "simultaneous_use_of_idtags", "multiple_simultaneous_sessions_remotely_and_idtags" ], "description": "Determine the number of sessions a user could start - single or multiple simultaneous sessions, or whether the user could start simultaneous sessions with several Id Tags." } } }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date" }, "receiveNewsAndPromotions": { "type": "boolean", "example": true, "description": "Updates the user's preference for receiving news and promotions. To change their preference, update this field to 'true' to opt in, or 'false' to opt out." }, "bankDetails": { "type": "object", "properties": { "bankIban": { "type": "string", "nullable": true, "description": "IBAN of the bank account." }, "bankCode": { "type": "string", "nullable": true, "description": "Bank code assigned by a central bank, a bank supervisory body or a Bankers Association in the country." }, "bankAccountNumber": { "type": "string", "nullable": true, "description": "Bank account number." }, "bankAccountType": { "type": "string", "nullable": true, "description": "Type of the bank account." }, "bankBic": { "type": "string", "nullable": true, "description": "BIC/SWIFT code of the bank." } } }, "externalAppData": { "type": "object", "additionalProperties": true, "example": { "externalCustomerId": "uuid" }, "nullable": true, "description": "The externalAppData field is an object designed to hold additional data related to external integrations. This object can contain the following keys, which are currently supported: - `externalCustomerId`: A string representing the customer ID of the user in an external payment provider integration. This ID is used to link the user's account within the system to their corresponding account in the external payment provider. If no information is available, the externalAppData object will be null. It's a part of the response only if request is called with `include.externalAppData` query parameter." } } } } } }, "responses": { "200": { "description": "User updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.1/{user}/notes", "method": "GET", "operationId": "userNotesListing", "summary": "User / Notes / Listing", "description": "List all notes for a specific user. Notes are returned with pinned notes first, then ordered by creation date descending. **Required permission:** `Notes.view`", "tags": [ "resource / users" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "pinned": { "type": "boolean", "example": true, "description": "Filter by pinned status" }, "createdAfter": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z", "description": "Filter notes created on or after this ISO-8601 datetime" }, "createdBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes created on or before this ISO-8601 datetime" }, "updatedAfter": { "type": "string", "format": "date-time", "example": "2025-12-01T00:00:00Z", "description": "Filter notes updated on or after this ISO-8601 datetime (useful for delta sync)" }, "updatedBefore": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z", "description": "Filter notes updated on or before this ISO-8601 datetime" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.1/{user}/notes", "method": "POST", "operationId": "userNoteCreate", "summary": "User / Note / Create", "description": "Create a new note for a specific user. **Required permission:** `Notes.create`", "tags": [ "resource / users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Important maintenance note", "description": "Short summary or title of the note (required)" }, "details": { "type": "string", "maxLength": 2000, "example": "This charge point requires monthly inspection due to high usage.", "description": "Detailed content of the note (optional)" }, "pinned": { "type": "boolean", "default": false, "example": false, "description": "Whether the note should be pinned (optional, defaults to false)" } }, "required": [ "summary" ] } } } }, "responses": { "201": { "description": "Note created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.1/{user}/notes/{note}", "method": "GET", "operationId": "userNoteShow", "summary": "User / Note / Read", "description": "Get a specific note for a user. **Required permission:** `Notes.view`", "tags": [ "resource / users" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.1/{user}/notes/{note}", "method": "DELETE", "operationId": "userNoteDelete", "summary": "User / Note / Delete", "description": "Delete a specific note from a user. Notes are permanently deleted (hard delete). **Required permission:** `Notes.delete`", "tags": [ "resource / users" ], "responses": { "204": { "description": "Note deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/users/v1.1/{user}/notes/{note}", "method": "PATCH", "operationId": "userNoteUpdate", "summary": "User / Note / Update", "description": "Update a specific note for a user. **Required permissions:** - `Notes.update` for updating summary and details - `Notes.pin` for updating the pinned field (in addition to Notes.update if other fields are included)", "tags": [ "resource / users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 255, "example": "Updated maintenance note", "description": "Short summary or title of the note" }, "details": { "type": "string", "maxLength": 2000, "example": "Updated inspection schedule.", "nullable": true, "description": "Detailed content of the note. Send null to clear." }, "pinned": { "type": "boolean", "example": true, "description": "Whether the note should be pinned. Requires Notes.pin permission." } } } } } }, "responses": { "200": { "description": "Note updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/utilities/v1.0", "method": "GET", "operationId": "listUtilities", "summary": "Utilities / Listing", "description": "Get all Utilities", "tags": [ "resource / utilities" ], "parameters": { "query": { "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/utilities/v1.0", "method": "POST", "operationId": "createUtility", "summary": "Utilities / Create", "description": "Create Utility", "tags": [ "resource / utilities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/utilities/v1.0/{utility}", "method": "GET", "operationId": "getUtility", "summary": "Utilities / Read", "description": "Get a single Utility", "tags": [ "resource / utilities" ], "parameters": { "path": { "utility": { "description": "The ID of the utility", "type": "integer", "required": true } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/utilities/v1.0/{utility}", "method": "PUT", "operationId": "updateUtility", "summary": "Utilities / Update", "description": "Update a single Utility", "tags": [ "resource / utilities" ], "parameters": { "path": { "utility": { "description": "The ID of the utility", "type": "integer", "required": true } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/utilities/v1.0/{utility}", "method": "DELETE", "operationId": "deleteUtility", "summary": "Utilities / Delete", "description": "Delete a single Utility", "tags": [ "resource / utilities" ], "parameters": { "path": { "utility": { "description": "The ID of the utility", "type": "integer", "required": true } } }, "responses": { "204": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vehicles/v1.0", "method": "GET", "operationId": "vehiclesListing", "summary": "Vehicles / Listing", "description": "Get a list of vehicles.", "tags": [ "resource / vehicles" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "format": "integer", "description": "Only list vehicles assigned to the given user." }, "partnerId": { "type": "string", "format": "integer", "description": "Only list vehicles attached to the partner." }, "usageType": { "type": "string", "enum": [ "private", "company" ], "description": "How the vehicle is used. * `private` - Private vehicle * `company` - Company or fleet vehicle" }, "label": { "type": "string", "description": "Case-insensitive partial match against vehicle label." }, "licensePlate": { "type": "string", "description": "Case-insensitive partial match against license plate." }, "vin": { "type": "string", "description": "Case-insensitive partial match against VIN." }, "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "createdAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the vehicles that were created on and after this datetime." }, "createdBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the vehicles that were created on and before this datetime." }, "lastUpdatedAfter": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the vehicles that were last updated on and after this datetime." }, "lastUpdatedBefore": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted date. Lists only the vehicles that were last updated on and before this datetime." } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" } } }, { "path": "/public-api/resources/vehicles/v1.0", "method": "POST", "operationId": "vehicleCreate", "summary": "Vehicle / Create", "description": "Create a new vehicle.", "tags": [ "resource / vehicles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "partnerId": { "type": "integer", "example": 12, "description": "Partner the vehicle belongs to." }, "label": { "type": "string", "maxLength": 255, "example": "Fleet car #4", "description": "Display name for the vehicle." }, "licensePlate": { "type": "string", "maxLength": 255, "example": "CA1234XY", "description": "License plate of the vehicle." }, "vin": { "type": "string", "minLength": 17, "maxLength": 17, "pattern": "^[A-HJ-NPR-Z0-9]{17}$", "example": "1HGBH41JXMN109186", "description": "Vehicle Identification Number (ISO 3779). Exactly 17 characters. Unique per operator." }, "pcId": { "type": "string", "maxLength": 255, "example": "DE8ABC1234567890", "description": "Provisioning certificate ID from the vehicle's ISO 15118 Plug & Charge system. The platform uses this value to automatically associate the vehicle with an EMAID contract certificate when the issued certificate has the same `pcId`." }, "usageType": { "type": "string", "enum": [ "private", "company" ], "description": "How the vehicle is used. * `private` - Private vehicle * `company` - Company or fleet vehicle" }, "userIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs of users to assign to the vehicle on creation." } }, "required": [ "label" ] } } } }, "responses": { "201": { "description": "Vehicle created successfully." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/vehicles/v1.0/telemetry-readings", "method": "GET", "operationId": "vehicleTelemetryReadingsListing", "summary": "Vehicle telemetry readings / listing", "description": "Get a list of vehicle telemetry readings.", "tags": [ "resource / vehicles" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "vehicleId": { "type": "integer" }, "source": { "type": "string", "enum": [ "api", "app" ], "description": "The channel a telemetry reading was submitted through. Set automatically by the platform; callers cannot override it. Values: - `api`: Submitted through the Public API. - `app`: Submitted through the mobile app." }, "partnerId": { "type": "integer" }, "submittedAfter": { "type": "string", "format": "date-time" }, "submittedBefore": { "type": "string", "format": "date-time" } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/vehicles/v1.0/{vehicle}", "method": "GET", "operationId": "vehicleRead", "summary": "Vehicle / Read", "description": "Get a vehicle by ID.", "tags": [ "resource / vehicles" ], "parameters": { "query": { "include": { "description": "Include additional information in the response. The following options are available:
- `userIds`: IDs of the users assigned to the vehicle.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "userIds" ] } } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/vehicles/v1.0/{vehicle}", "method": "DELETE", "operationId": "vehicleDelete", "summary": "Vehicle / Delete", "description": "Delete a vehicle.", "tags": [ "resource / vehicles" ], "responses": { "204": { "description": "Vehicle deleted successfully." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/vehicles/v1.0/{vehicle}", "method": "PATCH", "operationId": "vehicleUpdate", "summary": "Vehicle / Update", "description": "Update a vehicle.", "tags": [ "resource / vehicles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partnerId": { "type": "integer", "example": 12, "nullable": true, "description": "Partner the vehicle belongs to. Pass an integer to associate, `null` to clear, omit to preserve." }, "label": { "type": "string", "maxLength": 255, "example": "Fleet car #4", "description": "Display name for the vehicle." }, "licensePlate": { "type": "string", "maxLength": 255, "example": "CA1234XY", "nullable": true, "description": "License plate of the vehicle." }, "vin": { "type": "string", "minLength": 17, "maxLength": 17, "pattern": "^[A-HJ-NPR-Z0-9]{17}$", "example": "1HGBH41JXMN109186", "nullable": true, "description": "Vehicle Identification Number (ISO 3779). Exactly 17 characters. Unique per operator." }, "pcId": { "type": "string", "maxLength": 255, "example": "DE8ABC1234567890", "nullable": true, "description": "Provisioning certificate ID from the vehicle's ISO 15118 Plug & Charge system. The platform uses this value to automatically associate the vehicle with an EMAID contract certificate when the issued certificate has the same `pcId`." }, "usageType": { "type": "string", "enum": [ "private", "company" ], "nullable": true, "description": "How the vehicle is used. * `private` - Private vehicle * `company` - Company or fleet vehicle" }, "userIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs of users assigned to the vehicle." } } } } } }, "responses": { "200": { "description": "Vehicle updated successfully." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/vehicles/v1.0/{vehicle}/relations/users", "method": "GET", "operationId": "vehicleUsersListing", "summary": "Vehicle / Users / Listing", "description": "List the IDs of the users currently assigned to the vehicle.", "tags": [ "resource / vehicles" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/vehicles/v1.0/{vehicle}/relations/users", "method": "POST", "operationId": "vehicleUsersAttach", "summary": "Vehicle / Users / Attach", "description": "Attach one or more users to the vehicle. Idempotent — attaching a user that is already assigned is a silent no-op. The response returns the post-operation user ID list.", "tags": [ "resource / vehicles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs of users assigned to the vehicle." } }, "required": [ "userIds" ] } } } }, "responses": { "200": { "description": "Vehicle users attached successfully." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/vehicles/v1.0/{vehicle}/relations/users", "method": "PUT", "operationId": "vehicleUsersReplace", "summary": "Vehicle / Users / Replace", "description": "Replace the full set of users assigned to the vehicle. Pass `{ \"userIds\": [...] }` with the complete desired assignment. Sending `[]` detaches every user. The response returns the post-operation user ID list.", "tags": [ "resource / vehicles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs of users assigned to the vehicle." } }, "required": [ "userIds" ] } } } }, "responses": { "200": { "description": "Vehicle users replaced successfully." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/vehicles/v1.0/{vehicle}/relations/users/{user}", "method": "DELETE", "operationId": "vehicleUsersDetach", "summary": "Vehicle / Users / Detach", "description": "Detach a single user from the vehicle. Returns the post-operation user ID list. Detaching a user that is not currently assigned returns `404`.", "tags": [ "resource / vehicles" ], "responses": { "200": { "description": "Vehicle user detached successfully." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/vehicles/v1.0/{vehicle}/telemetry-readings", "method": "GET", "operationId": "vehicleTelemetryReadingsByVehicleListing", "summary": "Vehicle telemetry readings / Listing", "description": "List telemetry readings for a vehicle, ordered by submission time descending.", "tags": [ "resource / vehicles" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "api", "app" ], "description": "The channel a telemetry reading was submitted through. Set automatically by the platform; callers cannot override it. Values: - `api`: Submitted through the Public API. - `app`: Submitted through the mobile app." }, "submittedAfter": { "type": "string", "format": "date-time", "description": "Return readings submitted at or after this moment." }, "submittedBefore": { "type": "string", "format": "date-time", "description": "Return readings submitted at or before this moment." } } } }, "per_page": { "description": "The number of items to return per page.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/vehicles/v1.0/{vehicle}/telemetry-readings", "method": "POST", "operationId": "vehicleTelemetryReadingCreate", "summary": "Vehicle telemetry reading / Create", "description": "Submit a new telemetry reading for a vehicle.", "tags": [ "resource / vehicles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "odometerKm": { "type": "number", "minimum": 0, "maximum": 999999999.999, "example": 12345.678, "description": "Odometer value in kilometres. Must be greater than 0 and no more than 999999999.999 when provided. At least one measurement field must be present on a reading; in this version `odometerKm` is the only measurement field." }, "submittedAt": { "type": "string", "format": "date-time", "example": "2026-01-15T10:00:00+00:00", "description": "When the reading was taken. Defaults to the request time when omitted." }, "submittedByUserId": { "type": "integer", "example": 88, "description": "The user who submitted the reading. Must belong to the same operator as the vehicle. Stored without a user association when omitted." } }, "description": "Payload for submitting a new vehicle telemetry reading." } } } }, "responses": { "201": { "description": "Telemetry reading created successfully." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "422": { "description": "The payload you provided is invalid" } } }, { "path": "/public-api/resources/vehicles/v1.0/{vehicle}/telemetry-readings/{vehicleTelemetryReading}", "method": "DELETE", "operationId": "vehicleTelemetryReadingDelete", "summary": "Vehicle telemetry reading / Delete", "description": "Delete an erroneous telemetry reading.", "tags": [ "resource / vehicles" ], "responses": { "204": { "description": "Telemetry reading deleted successfully." }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" } } }, { "path": "/public-api/resources/vendor-error-codes/v2.0", "method": "GET", "operationId": "vendorErrorCodesListing", "summary": "Vendor Error Codes / Listing", "description": "Get all Vendor Error Codes", "tags": [ "resource / vendor error codes" ], "parameters": { "query": { "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vendor-error-codes/v2.0", "method": "POST", "operationId": "vendorErrorCodeCreate", "summary": "Vendor Error Code / Create", "description": "Create new Vendor Error Code", "tags": [ "resource / vendor error codes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "vendorId": { "type": "string", "description": "Unique identifier of the Vendor, reported from the Charge point" }, "errorCode": { "type": "string", "description": "The code reported from the charge point when the hardwareStatus is faulted" }, "errorCodeDescription": { "type": "string", "nullable": true, "description": "Description of the error provided by the vendor" }, "errorCodeCustomerAction": { "type": "string", "nullable": true, "description": "Recommended actions by the customer when this error occurs" } }, "required": [ "vendorId", "errorCode" ] } } } }, "responses": { "201": { "description": "Vendor Error Codes created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vendor-error-codes/v2.0/{vendorErrorCode}", "method": "GET", "operationId": "vendorErrorCodeRead", "summary": "Vendor Error Code / Read", "description": "Get a Vendor Error Code", "tags": [ "resource / vendor error codes" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vendor-error-codes/v2.0/{vendorErrorCode}", "method": "DELETE", "operationId": "vendorErrorCodeDelete", "summary": "Vendor Error Code / Delete", "description": "Delete a Vendor Error Code", "tags": [ "resource / vendor error codes" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vendor-error-codes/v2.0/{vendorErrorCode}", "method": "PATCH", "operationId": "vendorErrorCodeUpdate", "summary": "Vendor Error Code / Update", "description": "Vendor Error Code", "tags": [ "resource / vendor error codes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "vendorId": { "type": "string", "description": "Unique identifier of the Vendor, reported from the Charge point" }, "errorCode": { "type": "string", "description": "The code reported from the charge point when the hardwareStatus is faulted" }, "errorCodeDescription": { "type": "string", "nullable": true, "description": "Description of the error provided by the vendor" }, "errorCodeCustomerAction": { "type": "string", "nullable": true, "description": "Recommended actions by the customer when this error occurs" } }, "required": [ "vendorId", "errorCode" ] } } } }, "responses": { "200": { "description": "Vendor Error Codes updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vouchers/v2.0", "method": "GET", "operationId": "vouchersListingDeprecated", "summary": "Vouchers / Listing", "description": "Get all Vouchers", "deprecated": true, "tags": [ "resource / vouchers" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "voucher", "manual_top_up", "auto_top_up", "top_up_by_operator", "api_top_up", "promo_code", "subscribe_to_plan" ], "description": "Lists only vouchers that are with one of these types `voucher`, `manual_top_up`, `top_up_auto`, `auto_top_up`, `top_up_by_operator`, `api_top_up`, `promo_code`, `subscribe_to_plan`." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Lists only the vouchers that are with one of these statuses `enabled`, `disabled`." }, "createdAt": { "type": "string", "format": "date", "description": "Lists only vouchers that are created on a particular date. Please provide the value in the following format `yyyy-mm-dd`." }, "redeemedAfter": { "type": "string", "format": "date-time", "description": "Lists only vouchers that are redeemed after the specified date and time. Please provide the value in ISO 8601 formatted date." }, "redeemedBefore": { "type": "string", "format": "date-time", "description": "Lists only vouchers that were redeemed before the specified date and time. Please provide the value in ISO 8601 formatted date." }, "userId": { "type": "integer", "description": "Lists only vouchers that were redeemed by a particular user." } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vouchers/v2.0", "method": "POST", "operationId": "voucherCreateDeprecated", "summary": "Voucher / Create", "description": "Create new Voucher", "deprecated": true, "tags": [ "resource / vouchers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "expireDate": { "type": "string", "format": "date", "nullable": true, "description": "RFC 3339 formatted date" }, "description": { "type": "string" } }, "required": [ "amount" ] } } } }, "responses": { "201": { "description": "Voucher created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vouchers/v2.0/{voucher}", "method": "GET", "operationId": "voucherReadDeprecated", "summary": "Voucher / Read", "description": "Get a Voucher", "deprecated": true, "tags": [ "resource / vouchers" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vouchers/v2.0/{voucher}", "method": "DELETE", "operationId": "voucherDeleteDeprecated", "summary": "Voucher / Delete", "description": "Delete a Voucher", "deprecated": true, "tags": [ "resource / vouchers" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vouchers/v2.0/{voucher}", "method": "PATCH", "operationId": "voucherUpdateDeprecated", "summary": "Voucher / Update", "description": "Update a Voucher", "deprecated": true, "tags": [ "resource / vouchers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "expireDate": { "type": "string", "format": "date", "nullable": true, "description": "RFC 3339 formatted date" }, "amount": { "type": "number", "format": "float" } }, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "Voucher updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vouchers/v2.1", "method": "GET", "operationId": "vouchersListing", "summary": "Vouchers / Listing", "description": "Get all Vouchers", "tags": [ "resource / vouchers" ], "parameters": { "query": { "filter": { "schema": { "type": "object", "properties": { "operatorId": { "example": "1", "oneOf": [ { "type": "string", "format": "integer" }, { "type": "array", "items": { "type": "string", "format": "integer" } } ], "description": "Filter by operator ID(s). **For operator-scoped tokens:** If provided, must match the token's operator. Returns empty results if a different operator ID is specified. **For global admin tokens:** Returns resources from the specified operator(s). Multiple IDs can be provided to filter by multiple operators. **Usage examples:** - Single operator: `?filter[operatorId]=1` - Multiple operators: `?filter[operatorId][]=1&filter[operatorId][]=2`" }, "type": { "type": "string", "enum": [ "voucher", "manual_top_up", "auto_top_up", "top_up_by_operator", "api_top_up", "promo_code", "subscribe_to_plan" ], "description": "Lists only vouchers that are with one of these types `voucher`, `manual_top_up`, `top_up_auto`, `auto_top_up`, `top_up_by_operator`, `api_top_up`, `promo_code`, `subscribe_to_plan`." }, "purpose": { "type": "string", "enum": [ "single", "multi" ], "example": "single", "description": "Indicates the tax treatment of the voucher under EU regulation 2016/1065. - **single**: Single-purpose voucher (SPV) — taxed at purchase and limited to sessions matching its original tax rate. - **multi**: Multi-purpose voucher (MPV) — taxed when spent and can pay for sessions with any tax rate. The `multi` value only appears on vouchers created while the `balance-with-multipurpose-vouchers` feature flag is enabled." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Lists only the vouchers that are with one of these statuses `enabled`, `disabled`." }, "createdAt": { "type": "string", "format": "date", "description": "Lists only vouchers that are created on a particular date. Please provide the value in the following format `YYYY-MM-DD`." }, "redeemedAfter": { "type": "string", "format": "date-time", "description": "Lists only vouchers that are redeemed after the specified date and time. Please provide the value in ISO 8601 formatted date." }, "redeemedBefore": { "type": "string", "format": "date-time", "description": "Lists only vouchers that were redeemed before the specified date and time. Please provide the value in ISO 8601 formatted date." }, "userId": { "type": "integer", "description": "Lists only vouchers that were redeemed by a particular user." }, "expireDateAfter": { "type": "string", "format": "date", "description": "Lists only vouchers with expiration date after the specified date. Please provide the value in RFC 3339 formatted date `YYYY-MM-DD`." }, "expireDateBefore": { "type": "string", "format": "date", "description": "Lists only vouchers with expiration date before the specified date. Please provide the value in RFC 3339 formatted date `YYYY-MM-DD`." }, "code": { "type": "string", "description": "Lists only vouchers with code which contains the specified string. Please provide min 3 chars value." } } } }, "page": { "description": "DEPRECATED - Sunset date: Mon, 01 Jun 2026 The page number to fetch (defaults to 1). Not used in cursor pagination. **This parameter is deprecated and will be removed on Mon, 01 Jun 2026.** Use cursor pagination instead for better performance and consistency. See the cursor parameter below for details.", "type": "integer", "default": 1 }, "per_page": { "description": "The numbers of items to return. Used in both page and cursor pagination to declare the page size.", "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "description": "The cursor to fetch the next page. **Do not construct this value manually.** Use one of the following methods: - Use the value from the previous response's `links.next` to fetch the next page - Pass an empty string (e.g., `?cursor` or `?cursor=`) to initiate cursor pagination on the first page", "type": "string" } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vouchers/v2.1", "method": "POST", "operationId": "voucherCreate", "summary": "Voucher / Create", "description": "Create new Voucher", "tags": [ "resource / vouchers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "example": 1, "nullable": true, "description": "The operator ID for this resource. Required for global admin tokens. Optional for operator-scoped tokens (defaults to token's operator)." }, "amount": { "type": "number", "format": "float" }, "expireDate": { "type": "string", "format": "date", "nullable": true, "description": "RFC 3339 formatted date. Defines the date on which the voucher expires. The field can be calculated based on the `redeemedAt` timestamp and the `validityPeriod` field if the `validityPeriod` is set and the `expireDate` is not." }, "validityPeriod": { "type": "string", "enum": [ "2 days", "1 week", "2 weeks", "1 month", "3 months", "6 months", "1 year", "2 years", "3 years", "5 years" ], "nullable": true, "description": "Defines the validity period for the voucher. When a user redeems the voucher, this period is added to the `redeemedAt` timestamp to calculate the voucher's `expireDate`. This field is only used when `expireDate` is not already set - if `expireDate` has a value, this period is ignored and the defined `expireDate` is used instead." }, "assignBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "The date before which the voucher should be assigned to user in order to be valid. RFC 3339 formatted date" }, "description": { "type": "string" }, "prefix": { "type": "string", "minLength": 3, "maxLength": 3, "description": "The prefix of the voucher's code." }, "title": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "The title of the voucher." } }, "required": [ "amount" ] } } } }, "responses": { "201": { "description": "Voucher created successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vouchers/v2.1/{voucher}", "method": "GET", "operationId": "voucherRead", "summary": "Voucher / Read", "description": "Get a Voucher", "tags": [ "resource / vouchers" ], "responses": { "200": { "description": "Success" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "404": { "description": "The record is not found" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vouchers/v2.1/{voucher}", "method": "DELETE", "operationId": "voucherDelete", "summary": "Voucher / Delete", "description": "Delete a Voucher", "tags": [ "resource / vouchers" ], "responses": { "204": { "description": "Deleted successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } }, { "path": "/public-api/resources/vouchers/v2.1/{voucher}", "method": "PATCH", "operationId": "voucherUpdate", "summary": "Voucher / Update", "description": "Update a Voucher", "tags": [ "resource / vouchers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "expireDate": { "type": "string", "format": "date", "nullable": true, "description": "RFC 3339 formatted date. Defines the date on which the voucher expires. The field can be calculated based on the `redeemedAt` timestamp and the `validityPeriod` field if the `validityPeriod` is set and the `expireDate` is not." }, "validityPeriod": { "type": "string", "enum": [ "2 days", "1 week", "2 weeks", "1 month", "3 months", "6 months", "1 year", "2 years", "3 years", "5 years" ], "nullable": true, "description": "Defines the validity period for the voucher. When a user redeems the voucher, this period is added to the `redeemedAt` timestamp to calculate the voucher's `expireDate`. This field is only used when `expireDate` is not already set - if `expireDate` has a value, this period is ignored and the defined `expireDate` is used instead." }, "assignBeforeDate": { "type": "string", "format": "date", "description": "The date before which the voucher should be assigned to user in order to be valid. RFC 3339 formatted date" }, "amount": { "type": "number", "format": "float" }, "prefix": { "type": "string", "minLength": 3, "maxLength": 3, "description": "The prefix of the voucher's code." }, "title": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "description": "valid locale" }, "translation": { "type": "string" } } }, "description": "The title of the voucher." } }, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "Voucher updated successfully" }, "401": { "description": "Access token is missing or invalid" }, "403": { "description": "You do not have permission to perform the action" }, "422": { "description": "The payload you provided is invalid" }, "429": { "description": "Too many requests. Please try again later. For more information, please check the rate limit headers X-RateLimit-*" } } } ], "info": { "title": "Public API", "version": "3.251.5", "description": "The Public API provides server-to-server integration capabilities for your EV charging platform.\n\n**Authentication.** Existing integrations continue to work unchanged — long-lived UUID admin tokens are sent in `Authorization: Bearer ...` with no exchange required. Two security schemes are documented for OpenAPI client tooling, both resulting in the same Bearer header at the wire level:\n - `bearerAuth` — the token in the `Authorization: Bearer ...` header is either a long-lived UUID admin token (issued via the admin UI, used directly) or a short-lived access token previously obtained via OAuth.\n - `oauth2ClientCredentials` - a `client_id` / `client_secret` pair should be exchanged for a short-lived access token at `/public-api/oauth/token` per RFC 6749 Section 4.4 (Client Credentials Grant), and the short-lived token should be used in the `Authorization: Bearer ...` header. The OAuth `client_secret` itself cannot be sent directly as a bearer token — it must be exchanged first.\n" }, "servers": [ { "url": "https://{tenantUrl}", "variables": { "tenantUrl": { "description": "The tenant identifier", "default": "example.com" } } } ], "buildTimestamp": "2026-09-21T07:34:58.385Z", "stats": { "totalEndpoints": 648, "originalSize": 6020721, "optimizedSize": 1671968, "reductionPercent": 72.23, "buildDuration": 1590, "responseSchemas": { "total": 648, "withSchemas": 648, "totalSchemaSize": 3455237, "averageSchemaSize": 5332 } } }