.. _pricing-dynamic-metadata:

Dynamic pricing metadata
------------------------
Every price response reports whether the rate is dynamic and, for a
dynamic rate, which schedule entry applies at the requested time. On
request it also returns the next price the driver will hit. This lets a
single Pricing API call show consistent current and ahead prices.

The schedules behind these fields are configured through the Dynamic
Pricing API (see :ref:`dynamic-pricing-modes`).

pricingType
===========
``pricingType`` states the rate's mode:

- ``0`` — static. No schedule; the rate has one fixed price.
- ``1`` — recurring per weekday. Prices repeat every week on set
  weekdays and time ranges.
- ``2`` — unique date and time. Prices tied to specific start timestamps.

Applied entry: scheduleUuid and validity
=========================================
For a dynamic rate, ``scheduleUuid`` and ``validity`` identify the
schedule entry active at the time of the request. ``validity`` takes one
of three forms, keyed by its ``type``:

- ``unique`` — ``start`` and ``end`` as ISO-8601 UTC. ``end`` is the next
  entry's start, or end of day for the last entry.
- ``recurring`` — the applicable weekday slot: its weekday, weekday name
  and ``HH:MM`` time range. Only the slot active at the requested time is
  returned, not the whole schedule.
- ``default`` — the recurring rate's fallback price in a gap where no slot
  covers. It carries the weekday and ``HH:MM`` window of the gap, and
  ``scheduleUuid`` is null.

``scheduleUuid`` and ``validity`` are null when:

- the rate is static (``pricingType`` ``0``);
- the rate is unique and the request time falls before its first entry.

A recurring rate always resolves to a slot or a default window, so it
always carries a ``validity``.

Next price
==========
Set ``next_price=true`` to add a ``nextPrice`` block for the next
applicable schedule entry. It carries the same ``scheduleUuid`` and
``validity`` fields as the current price, plus a full ``priceStructure``
in the Pricing API model. The block is present only for a dynamic rate
that has a following entry. A gap after the current slot yields a
``default`` ``nextPrice`` with a null ``scheduleUuid``.

For the full field list see `Datastructures <datastructures.html>`__, and
for worked examples the dynamic-rate requests under
`api/pricing - single evse id <single_evse_id.html>`__.