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.

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.

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.

Versions

Versions

Version

Description

Author

Date

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