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: .. code-block:: text x-api-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-params: .. rubric:: Cost rate optional parameters The following optional parameters are accepted by both the create and \ update cost rate endpoints: .. list-table:: :widths: 25 15 60 :header-rows: 1 * - 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: .. rubric:: 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: .. rubric:: 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: .. code-block:: json { "": { "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-schedule-scope: .. rubric:: 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 :ref:`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 ======== .. list-table:: Versions :widths: 10 20 20 50 :header-rows: 1 * - 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: .. code-block:: bash curl --location --request POST 'https://example.beenergised.cloud/api/dynamic_pricing/cost_rate' \ --header 'x-api-token: ' \ --header 'Content-Type: application/json' \ --data '{"name":"My Cost Rate","currency":"EUR"}' Endpoints ========= - :doc:`cost_rate_post` — ``POST /api/dynamic_pricing/cost_rate`` - :doc:`cost_rate_get` — ``GET /api/dynamic_pricing/cost_rate/{uuid}`` - :doc:`cost_rates_get` — ``GET /api/dynamic_pricing/cost_rates`` - :doc:`cost_rate_put` — ``PUT /api/dynamic_pricing/cost_rate`` - :doc:`cost_rate_delete` — ``DELETE /api/dynamic_pricing/cost_rate/{uuid}`` - :doc:`cost_rate_marketing_text_post` — \ ``POST /api/dynamic_pricing/cost_rate_marketing_text`` - :doc:`cost_rate_marketing_text_put` — \ ``PUT /api/dynamic_pricing/cost_rate_marketing_text`` - :doc:`cost_rate_marketing_text_get` — \ ``GET /api/dynamic_pricing/cost_rate_marketing_text`` - :doc:`cost_rate_session_fee_get` — \ ``GET /api/dynamic_pricing/cost_rate_session_fee/{uuid}`` - :doc:`cost_rate_session_fee_put` — \ ``PUT /api/dynamic_pricing/cost_rate_session_fee`` - :doc:`recurring_pricing_config_get` — \ ``GET /api/dynamic_pricing/recurring_pricing_config/{cost_rate_uuid}`` - :doc:`recurring_pricing_config_post` — \ ``POST /api/dynamic_pricing/recurring_pricing_config`` - :doc:`recurring_pricing_config_put` — \ ``PUT /api/dynamic_pricing/recurring_pricing_config/{uuid}`` - :doc:`recurring_pricing_config_delete` — \ ``DELETE /api/dynamic_pricing/recurring_pricing_config/{uuid}`` - :doc:`recurring_pricing_config_by_weekday_delete` — \ ``DELETE /api/dynamic_pricing/recurring_pricing_config/``\ ``{cost_rate_uuid}/weekday/{weekday}`` - :doc:`unique_pricing_config_get` — \ ``GET /api/dynamic_pricing/unique_pricing_config/{cost_rate_uuid}`` - :doc:`unique_pricing_config_post` — \ ``POST /api/dynamic_pricing/unique_pricing_config`` - :doc:`unique_pricing_config_put` — \ ``PUT /api/dynamic_pricing/unique_pricing_config/{uuid}`` - :doc:`unique_pricing_config_delete` — \ ``DELETE /api/dynamic_pricing/unique_pricing_config/{uuid}`` - :doc:`unique_schedule_get` — \ ``GET /api/dynamic_pricing/unique_schedule/{cost_rate_uuid}`` - :doc:`recurring_schedule_get` — \ ``GET /api/dynamic_pricing/recurring_schedule/{cost_rate_uuid}`` - :doc:`next_schedule_get` — \ ``GET /api/dynamic_pricing/next_schedule/{cost_rate_uuid}/``\ ``{schedule_uuid}`` - :doc:`cost_rate_time_costs_get` — \ ``GET /api/dynamic_pricing/cost_rate_time_costs/{cost_rate_uuid}`` - :doc:`cost_rate_time_cost_post` — \ ``POST /api/dynamic_pricing/cost_rate_time_cost`` - :doc:`cost_rate_time_cost_put` — \ ``PUT /api/dynamic_pricing/cost_rate_time_cost`` - :doc:`cost_rate_time_cost_delete` — \ ``DELETE /api/dynamic_pricing/cost_rate_time_cost/{uuid}`` - :doc:`cost_rate_energy_cost_get` — \ ``GET /api/dynamic_pricing/cost_rate_energy_cost/{cost_rate_uuid}`` - :doc:`cost_rate_energy_cost_post` — \ ``POST /api/dynamic_pricing/cost_rate_energy_cost`` - :doc:`cost_rate_energy_cost_put` — \ ``PUT /api/dynamic_pricing/cost_rate_energy_cost`` - :doc:`cost_rate_energy_cost_delete` — \ ``DELETE /api/dynamic_pricing/cost_rate_energy_cost/{uuid}`` .. toctree:: :hidden: cost_rate_post.rst cost_rate_get.rst cost_rates_get.rst cost_rate_put.rst cost_rate_delete.rst cost_rate_marketing_text_post.rst cost_rate_marketing_text_put.rst cost_rate_marketing_text_get.rst cost_rate_session_fee_get.rst cost_rate_session_fee_put.rst recurring_pricing_config_get.rst recurring_pricing_config_post.rst recurring_pricing_config_put.rst recurring_pricing_config_delete.rst recurring_pricing_config_by_weekday_delete.rst unique_pricing_config_get.rst unique_pricing_config_post.rst unique_pricing_config_put.rst unique_pricing_config_delete.rst unique_schedule_get.rst recurring_schedule_get.rst next_schedule_get.rst cost_rate_time_costs_get.rst cost_rate_time_cost_post.rst cost_rate_time_cost_put.rst cost_rate_time_cost_delete.rst cost_rate_energy_cost_get.rst cost_rate_energy_cost_post.rst cost_rate_energy_cost_put.rst cost_rate_energy_cost_delete.rst