Charging Policies (beta)
No OAuth-enabled endpoints in this section. Turn off the OAuth filter in the sidebar to see all of its endpoints.
No Road deviations in this section. Turn off the deviations filter in the sidebar to see all of its endpoints.
A charging policy holds the price of a charging session and the rules that decide who is allowed to charge at that price.
How the pieces fit together
- A policy carries one or more tariff rules. Each rule holds a tariff configuration (the price components) and, optionally, the customer groups it applies to. A rule with an empty
customerGroupIdsapplies to every token presented. - A policy is applied to connectors by associating it with one or more charging groups through
associatedChargingGroupIds. A charging group selects connectors individually, or by the locations or accounts they belong to. A provider policy with an emptyassociatedChargingGroupIdsapplies to every charging station instead; a provider can have only one such policy, and account-owned policies (/mine) never apply this way. - When a token is presented at a connector, the platform evaluates the policies that cover that connector in order: account policies first, then the provider's policies, each by
priority(1 first), and policies that apply to every charging station last. Within a policy, tariff rules are evaluated in the order they were supplied. The first rule that matches the token both authorises the session and prices it. priorityis numbered 1..n without gaps: one list for the provider's own policies and one per account. A new policy goes to the bottom of its list. Change the order withPUT /1/charging-policies/order(/mine/orderfor an account's own policies). Policies that apply to every charging station have no priority.- To give one card a different price (a negotiated rate, or free charging), put that card in a customer group and add a rule naming that group above the open rule in the same policy. The card matches the first rule and gets its price; every other card falls through to the open one.
This API is in preview. It is functional and safe to build against, but breaking changes may still occur; any breaking change is announced in advance.
Create Charging Policy
Creates a charging policy for the current provider and associates it with the charging groups listed in associatedChargingGroupIds. Returns the id of the created policy.
Each tariff rule carries its price inline under tariffConfiguration. The tariff configuration is stored as its own record and reads of the policy return it as tariffRules[].tariffConfigurationId, so tariffConfiguration.id only needs to be sent when reusing an existing configuration.
Rules are evaluated in the order they are supplied and the first rule matching the presented token wins, so list the most specific rule first. Leave customerGroupIds empty for a rule that should apply to every token, and leave paymentOptions empty unless the rule should be restricted to charge cards (CHARGE_CARD) or ad-hoc payment (AD_HOC) — a rule restricted to a payment option is skipped for tokens authorised by any other means.
User sessionAPI credentialcharging-policies:writeRequest bodyapplication/json
Charging groups the policy applies to. Send an empty list to apply the policy to every charging station of the provider; only one policy per provider can be left without charging groups, and a second one is rejected. Reads return an empty list for such a policy.
sessionLimitsobject
tariffRulesobject[]REQUIRED
tariffConfigurationobjectREQUIRED
configurationobjectREQUIRED
marketEnergyPricingobject
AUTBELDEUFRANLDvalidityPeriodobject
201Created application/json
dataobject
metaobject
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
403Forbidden: missing a required permission, or no access to this resource application/json
errorobject
404Not Found application/json
errorobject
500Internal server error application/json
errorobject
Get Charging Policy Order
Returns the order in which the current provider's own charging policies are evaluated, and the version to send back with a new order. Account policies have an order of their own and are not part of it.
User sessionAPI credentialcharging-policies:read200Charging Policy Order application/json
dataChargingPolicyOrder
Ids of the owner's policies that have a priority, priority 1 first. Policies that apply to every charging station have no priority and are not listed.
Changes with every change to this order. Send it back when you save a new order.
metaobject
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
403Forbidden: missing a required permission, or no access to this resource application/json
errorobject
404Not Found application/json
errorobject
500Internal server error application/json
errorobject
Reorder Charging Policies
Saves a new evaluation order for the current provider's own charging policies. Send all of its prioritised policies in the new order, with the version the order was loaded with.
User sessionAPI credentialcharging-policies:writeRequest bodyapplication/json
Every policy of the owner that has a priority, in the new order. The first gets priority 1.
The version the order was loaded with.
0max 4294967295200Reordered application/json
dataChargingPolicyOrderVersion
Send it back with the next reorder.
metaobject
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
403Forbidden: missing a required permission, or no access to this resource application/json
errorobject
404Not Found application/json
errorobject
409The order changed since it was loaded, or chargingPolicyIds is not exactly the prioritised policies of the owner. error.type is CHARGING_POLICY_ORDER_CONFLICT. Load the order again and retry. application/json
errorobject
500Internal server error application/json
errorobject
Search Charging Policies
Returns a paginated list of charging policies for the current provider: its own policies by priority, then account policies by account and priority, then the policies that apply to every charging station, most recently updated first. Supports filtering by free-text query, creation date range, currencies, tariff price types, payment options, customer groups, and associated charging groups. As on the single-policy endpoint, the include query parameter expands referenced tariff configurations, customer groups and charging groups.
User sessionAPI credentialcharging-policies:readQuery parameters1
Comma-separated relationship paths to return as records instead of ids. Allowed: tariffRules.tariffConfigurationId, tariffRules.customerGroupIds, associatedChargingGroupIds
Request bodyapplication/json
Returns policies associated with any of these charging groups. A policy that applies to every charging station has no charging groups, so this filter never matches it.
createdAtany | any
Set to false to leave out the policies that accounts own.
50min 10min 0200Charging Policies application/json
dataPopulatedChargingPolicy[]
Charging groups the policy applies to. Empty on a provider policy means it applies to every charging station of the provider; empty on an account-owned policy means it targets connectors only (see associatedConnectors).
associatedChargingGroupsChargingGroup[]
filtersChargingGroupFilter[]REQUIREDThe connectors this group covers. A connector matches if any filter selects it.
The connectors this group covers. A connector matches if any filter selects it.
associatedConnectorsChargingPolicyConnectorAssociation[]
Evaluation order among the policies of the same owner: 1 is evaluated first. Numbered 1..n without gaps, one list for the provider's own policies and one per account. Absent on a policy that applies to every charging station: those are evaluated last.
sessionLimitsSessionLimits
tariffRulesPopulatedTariffRule[]REQUIRED
Customer groups the rule is restricted to. Empty means the rule applies to every token.
customerGroupsEmbeddedCustomerGroup[]
A token belongs to the group if it matches any one of these filters.
Restricts the rule to sessions paid for in these ways. Empty means the rule accepts any payment method.
Where this rule's price is advertised: roaming on roaming networks, csui on the charging station's own screen.
tariffConfigurationTariffConfiguration
The tariff (price) this rule applies.
validityPeriodobject
metaobject
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
403Forbidden: missing a required permission, or no access to this resource application/json
errorobject
404Not Found application/json
errorobject
500Internal server error application/json
errorobject
Get Charging Policy
Returns a single charging policy owned by the current provider, including its tariff rules. Tariff configurations, customer groups and charging groups are returned as ids by default; pass the include query parameter (tariffRules.tariffConfigurationId, tariffRules.customerGroupIds, associatedChargingGroupIds, comma-separated) to have them expanded into full objects.
User sessionAPI credentialcharging-policies:readPath parameters1
Query parameters1
Comma-separated relationship paths to return as records instead of ids. Allowed: tariffRules.tariffConfigurationId, tariffRules.customerGroupIds, associatedChargingGroupIds
200Charging Policy application/json
dataPopulatedChargingPolicy
Charging groups the policy applies to. Empty on a provider policy means it applies to every charging station of the provider; empty on an account-owned policy means it targets connectors only (see associatedConnectors).
associatedChargingGroupsChargingGroup[]
filtersChargingGroupFilter[]REQUIREDThe connectors this group covers. A connector matches if any filter selects it.
The connectors this group covers. A connector matches if any filter selects it.
associatedConnectorsChargingPolicyConnectorAssociation[]
Evaluation order among the policies of the same owner: 1 is evaluated first. Numbered 1..n without gaps, one list for the provider's own policies and one per account. Absent on a policy that applies to every charging station: those are evaluated last.
sessionLimitsSessionLimits
tariffRulesPopulatedTariffRule[]REQUIRED
Customer groups the rule is restricted to. Empty means the rule applies to every token.
customerGroupsEmbeddedCustomerGroup[]
A token belongs to the group if it matches any one of these filters.
Restricts the rule to sessions paid for in these ways. Empty means the rule accepts any payment method.
Where this rule's price is advertised: roaming on roaming networks, csui on the charging station's own screen.
tariffConfigurationTariffConfiguration
The tariff (price) this rule applies.
validityPeriodobject
metaobject
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
403Forbidden: missing a required permission, or no access to this resource application/json
errorobject
404Not Found application/json
errorobject
500Internal server error application/json
errorobject
Update Charging Policy
Replaces an existing charging policy: the full definition, including tariffRules and associatedChargingGroupIds, must be provided. Anything left out is removed — tariff rules that are not resent are dropped and their tariff configurations deleted, and charging group associations that are not resent are removed. To keep a rule on its existing tariff configuration, resend it with tariffConfiguration.id set.
A policy needs at least one tariff rule, so a request without tariffRules or with an empty list returns 400 and changes nothing.
User sessionAPI credentialcharging-policies:writePath parameters1
Request bodyapplication/json
Charging groups the policy applies to. Send an empty list to apply the policy to every charging station of the provider; only one policy per provider can be left without charging groups, and a second one is rejected. Reads return an empty list for such a policy.
sessionLimitsobject
tariffRulesobject[]REQUIRED
tariffConfigurationobjectREQUIRED
configurationobjectREQUIRED
marketEnergyPricingobject
AUTBELDEUFRANLDvalidityPeriodobject
204Updated text/plain
400Invalid Request application/json
errorobject
401Unauthorized application/json
errorobject
403Forbidden: missing a required permission, or no access to this resource application/json
errorobject
404Not Found application/json
errorobject
500Internal server error application/json
errorobject
Delete Charging Policy
Deletes a charging policy, including its tariff configurations and its charging group associations. The charging groups themselves are left in place. Connectors left without any applicable policy can no longer be priced, and sessions started there are rejected until another policy covers them.
User sessionAPI credentialcharging-policies:write