Pricing API
-----------
The pricing API gives the eMSP information about the tariffs used by each evse.
The API is secured with a token which can be read from the settings page in
your be.ENERGISED instance. The token must be passed as header `x-api-token`
within each request.

.. rubric:: Difference between the Pricing API and the Dynamic Pricing API

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.

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.

Use this API for anything scoped to a driver: which cost rate applies to them,
what they pay now, and what they pay once the current schedule window ends.
To read a rate's full schedule across a week or a series of dates, or to
create, change or delete a rate, use the :doc:`/dynamicPricingApi/index`.

A price response carries the link between the two. ``costId`` and
``costRateUuid`` identify the resolved cost rate, and ``scheduleUuid``
identifies the entry that produced the price. Pass ``costRateUuid`` to the
Dynamic Pricing API to read that rate's whole schedule, and ``scheduleUuid``
to step forward through it. Only read a schedule for a rate this API has
resolved for that driver — any other rate reports prices they will not be
charged.

For an example that uses both APIs together, see :doc:`price_timeline`.

Versions
========
.. list-table:: Versions
   :widths: 10 20 20 50
   :header-rows: 1

   * - Version
     - Description
     - Author
     - Date
   * - 1.0.0
     - Initial version
     - Robert Salchegger
     - 14.07.2020
   * - 1.1.0
     - Add all_paged endpoint and restructure documentation of separate endpoints
     - Robert Salchegger, Christian Zellot
     - 23.12.2020
   * - 1.1.1
     - Adapt documentation with a sample request including a header
     - Christian Zellot
     - 07.04.2021
   * - 1.2
     - Include tax information in price structure
     - Debraj Ghosh, Robert Salchegger
     - 09.08.2021
   * - 1.3
     - Include session fee in price structure
     - Tushar Timande
     - 30.4.2025
   * - 1.4
     - Expose dynamic-price metadata (costRateUuid, pricingType, applied scheduleUuid and validity) and opt-in ahead prices (next_price returns nextPrice)
     - Anthony Kamel
     - 07.07.2026
   * - 1.4.1
     - Describe the difference between the Pricing API and the Dynamic Pricing API in both introductions, add the price-timeline use case, and state that dynamic prices resolve in the station's local time
     - Anthony Kamel
     - 08.09.2026

Quickstart
==========

Prerequisites:

    - you have created an api token in the be.ENERGISED backend
    - you can see stations in your backend (either roaming stations
      or your own stations)
    - you have configured a rate which is attached to
      the authentication media

Sample curl request:

.. code-block:: bash

    curl --location --request GET 'https://yourinstancename.beenergised.cloud/api/pricing/?evseId=AT*HTB*E00008&tag_id=123456ABC' \
    --header 'x-api-token: your_token'

Endpoints
=========

The api offers multiple endpoints to receive the data for either
a specific evse, a list of evses or a full fetch method.

.. toctree::
   :maxdepth: 1

   single_evse_id.rst
   batch.rst
   all_paged.rst


Dynamic pricing metadata
========================
Each price response reports whether the rate is dynamic, which schedule applies
at the requested time, and, on request, the next price the driver will hit.

.. toctree::
   :maxdepth: 1

   dynamic_pricing.rst
   price_timeline.rst


Datastructures
==============
The api consists of different data structures, which are described here.

.. toctree::
   :maxdepth: 1

   datastructures.rst