Dynamic Pricing API

The Dynamic Pricing API allows you to manage Cost Rates (create, read, update, delete) and their Marketing Texts that can be used for dynamic pricing setups.

Difference between the Dynamic Pricing API and the Pricing API

The Dynamic Pricing API is contract-agnostic. It manages cost rates and their schedule entries, session fees and marketing texts, and identifies a rate by its uuid. It has no notion of a driver, a token or a contract, and cannot say which rate applies to anyone.

The Pricing API is contract-aware. It takes an evse id together with a driver’s token, emaid or authentication uuid, resolves the cost rate that applies to that driver at that station, and returns the price. For a dynamic rate it also reports the schedule entry the price came from and, on request, the next one. It only reads.

Use this API to create, change or delete cost rates, their schedule entries, session fees and marketing texts, and to read a rate’s full schedule across a week or a series of dates. To find out which rate applies to a given driver, or what that driver pays now and once the current schedule window ends, use the Pricing API.

The two are linked by the cost rate. A Pricing API response returns costId and costRateUuid for the rate it resolved, together with the scheduleUuid of the entry that produced the price. Those are the uuids to pass here to read the same rate’s schedule. Only show a driver a schedule for a rate the Pricing API has resolved for their token — any other rate reports prices they will not be charged.

For an example that uses both APIs together, see Showing a price timeline to a driver.

Authentication

The API is secured with a system token. The token must be included in every request as the X-api-token HTTP header. System tokens do not expire.

To create a token:

  1. Log in to your be.ENERGISED instance as an administrator.

  2. Navigate to Settings → System → API (e.g., https://example.beenergised.cloud/settings/system/api).

  3. In the System tokens section, click Order new system token.

  4. Fill in the form:

    • Unique description — A name to identify the token (e.g., dynamic-pricing-integration).

    • Limit access to IP — Optional. Restrict usage to a specific IP address for additional security.

  5. Confirm the order. The new token will appear in the Token column of the system tokens table.

  6. Copy the token value and include it as a header in every request:

x-api-token: <YOUR_TOKEN>

Note

The token is bound to the mandant (tenant) of your be.ENERGISED instance. All API requests are scoped to that mandant automatically. Ordering a system token may incur additional monthly fees depending on your be.ENERGISED contract.

Conventions

  • All examples use example.beenergised.cloud as domain; replace it with your instance URL.

  • All requests require the X-api-token header (see Authentication).

  • Cost rate write requests (POST, PUT) use Content-Type: application/json.

  • Marketing text write requests (POST, PUT) use Content-Type: application/x-www-form-urlencoded.

  • Read and delete requests (GET, DELETE) do not require a Content-Type header. They accept application/json responses.

Cost rate optional parameters

The following optional parameters are accepted by both the create and update cost rate endpoints:

Name

Type

Description

description

string|null

Description text.

automatic_stop_min

integer|null

Automatic stop after N minutes.

automatic_stop_costs

float|null

Automatic stop after reaching N costs.

dynamic_pricing

integer

0: dynamic pricing disabled, 1: recurring per weekday, 2: exact date and time.

company_id

integer|null

Optional company id scope.

Dynamic pricing modes

The dynamic_pricing parameter on a cost rate controls which type of pricing schedule configuration the cost rate uses. There are three modes:

  • 0 — Disabled (default): The cost rate uses a single, static pricing configuration with no time-based schedule variations.

  • 1 — Recurring per weekday: The cost rate supports recurring pricing configs — schedules that repeat every week on specified weekdays within a given time range. For example, a schedule that applies every Monday, Tuesday, and Wednesday from 18:00 to 22:00. Each schedule entry contains one or more weekday/time-range pairs. Manage these via the recurring_pricing_config endpoints.

  • 2 — Exact date and time: The cost rate supports unique pricing configs — one-off schedules tied to a specific date and time. For example, a special pricing rule that starts on 2026-01-01 at 00:00:00. Each config entry contains a single start timestamp. Manage these via the unique_pricing_config endpoints.

Note

A cost rate can only use one dynamic pricing mode at a time. Changing the dynamic_pricing value on a cost rate determines which set of schedule configuration endpoints can be used. Attempting to use recurring pricing config endpoints on a cost rate with dynamic_pricing = 2 (or vice versa) will return a 400 error.

How a dynamic pricing schedule resolves

Schedule entries apply in the local time of the charging station. A unique-date start is stored as submitted and read as a local time at the station; a recurring weekday slot applies in the same local time. An entry starting at 18:00 therefore applies at 18:00 local time at each station the cost rate covers. The timezone is resolved per station, taking the first of the following that yields a valid timezone: the station’s own timezone, derived from its coordinates when the station is provisioned; the timezone of the station’s country, where the country has exactly one; the timezone nearest the station’s coordinates, where the country has several; the mandant’s system timezone; UTC. The last two apply where the station’s own timezone, country and coordinates all fail to resolve.

A cost rate carries a default price, and schedule entries replace it for the periods they cover. The schedule endpoints list configured entries only, so the default price applies to every period outside them. On a recurring schedule that is the part of the week between two slots. On a unique-date schedule an entry prices only the day it starts on: it ends at the next entry that starts the same day, or at 23:59:59 of that day, and every remaining stretch of the calendar takes the default price, bounded day by day.

Marketing text structure

Marketing text endpoints accept and return texts keyed by locale. Each locale can contain up to three text types:

  • short_description — A short marketing summary.

  • description — A full description.

  • legal — Legal information or terms.

All text types are optional per locale. Multiple locales can be provided in a single request.

The marketing_texts body parameter must be a JSON-encoded string:

{
  "<locale>": {
    "short_description": "Short text",
    "description": "Longer description",
    "legal": "Legal notice"
  }
}

Note

Locales must follow the xx_XX format (e.g., it_IT, en_US, de_AT). Invalid locales will return a 400 error.

Marketing text scope

Marketing texts can be stored against two scopes:

  • Cost-rate default scope: the texts attached to the cost rate itself. Used when the rate_cost_schedule_uuid parameter is omitted.

  • Schedule-entry scope: texts attached to a single schedule entry — a recurring pricing config (dynamic_pricing = 1) or a unique pricing config (dynamic_pricing = 2). Used when rate_cost_schedule_uuid is passed.

The schedule scope is only available on cost rates whose dynamic_pricing mode is 1 or 2 (see Dynamic pricing modes). A static cost rate (dynamic_pricing = 0) has no schedule entries; passing rate_cost_schedule_uuid returns a 404 error.

Write requests (POST, PUT) store the texts on whichever scope the request targets; they do not write to both. The read endpoint (GET) applies a locale-level fallback when rate_cost_schedule_uuid is set: if the schedule entry has a translation row for a requested locale, all three text types for that locale are returned from the entry — including any fields stored as empty strings, which are not backfilled from the cost-rate default. If the entry has no translation row for a locale at all, the entire cost-rate default for that locale is used, so a locale defined only on the cost-rate default still resolves under a schedule-scoped read.

Reading applied and ahead prices

This API configures a cost rate’s schedules — its recurring and unique pricing configs. To read which price applies at a given time, and the next one, use the Pricing API. For a dynamic rate it returns the applied schedule entry (its uuid and validity) and, on request, the next price. See Dynamic pricing metadata.

For the call sequence that combines both APIs into a driver-facing price timeline across a day or a week, see Showing a price timeline to a driver.

Versions

Versions

Version

Description

Author

Date

1.9.0

Unique-date entries apply in the station’s local time: start is a naive local datetime, and an entry prices only the day it starts on

Anthony Kamel

08.09.2026

1.8.0

Added paginated schedule entry endpoints (unique_schedule, recurring_schedule, next_schedule)

Bahram Nedaei

02.06.2026

1.7.0

Changed marketing text GET response envelope: payload now under data as an object (was message as a JSON-encoded string). Breaking change.

Anthony Kamel

02.06.2026

1.6.0

Added optional rate_cost_schedule_uuid parameter on the marketing text endpoints (get, create, update)

Anthony Kamel

01.06.2026

1.5.0

Added cost rates list endpoint (paginated get)

Lisa Steiner

01.06.2026

1.4.0

Added energy cost endpoints (get, create, update, delete)

PRTAX-4116

03.04.2026

1.3.0

Added time-based cost endpoints (create, read, update, delete)

Almin Pupalovic

07.04.2026

1.2.0

Added recurring pricing config and unique pricing config endpoints

Anthony Kamel

07.04.2026

1.1.0

Added marketing text endpoints (create, update, get)

Anthony Kamel

05.03.2026

1.0.0

Initial version

Anthony Kamel

24.02.2026

Quickstart

Prerequisites:

  • you have obtained an API token (see Authentication above)

  • you have permission to create and edit cost rates

Sample curl request:

curl --location --request POST 'https://example.beenergised.cloud/api/dynamic_pricing/cost_rate' \
--header 'x-api-token: <your_token>' \
--header 'Content-Type: application/json' \
--data '{"name":"My Cost Rate","currency":"EUR"}'

Endpoints