Get Unique Pricing Schedule Entries
------------------------------------

Retrieve a paginated list of unique-date pricing schedule entries for \
a cost rate, optionally filtered to a UTC time window. The cost rate \
must have ``dynamic_pricing`` set to ``2`` (exact date and time \
— see :ref:`dynamic-pricing-modes`).

Each entry carries its full pricing payload — ``validity``, \
``intervals`` (energy + time + session fee, scoped to the entry only) \
and ``marketing_texts`` (locale-keyed, resolved with field-level \
fallback from the cost rate).

**Request**

- Method: ``GET``
- Path: ``/api/dynamic_pricing/unique_schedule/{cost_rate_uuid}``

**Path parameters**

.. list-table::
   :widths: 20 15 65
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - cost_rate_uuid
     - string
     - UUID of the cost rate. Must have ``dynamic_pricing`` set to \
       ``2`` (exact date and time).

**Query parameters**

.. list-table::
   :widths: 18 12 70
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - from
     - string|null
     - Optional inclusive lower bound. ISO-8601 datetime with an \
       **explicit timezone designator** (``Z`` or ``±HH:MM``); naked \
       timestamps return ``400``. Example: ``2026-06-01T00:00:00Z`` ✓; \
       ``2026-06-01T00:00:00`` ✗ (no timezone — returns ``400``).
   * - to
     - string|null
     - Optional exclusive upper bound, same format and validation as \
       ``from``. Must be strictly greater than ``from`` when both are \
       given.
   * - offset
     - integer
     - Page offset, ``>= 0``. Defaults to ``0``. Non-numeric values \
       are treated as ``0``.
   * - limit
     - integer
     - Page size. Defaults to ``100``, clamped to ``[1, 500]``.
   * - locales
     - string|string[]
     - Optional. Restricts the ``marketing_texts`` map on each entry \
       to the requested locale codes. Accepts \
       ``?locales[]=en_US&locales[]=de_DE`` or single \
       ``?locales=en_US``. Omit the parameter entirely to return every \
       locale the cost rate has. Non-string entries are dropped \
       silently.

**Example request**

.. code-block:: bash

    curl --location --request GET \
      'https://example.beenergised.cloud/api/dynamic_pricing/unique_schedule/<COST_RATE_UUID>?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z&offset=0&limit=100&locales[]=en_US' \
      --header 'x-api-token: <your_token>'

**Response (200)**

.. code-block:: json

    {
      "data": [
        {
          "uuid": "<SCHEDULE_UUID>",
          "name": "New Year Special",
          "validity": {
            "type": "unique",
            "start": "2026-01-01T00:00:00Z"
          },
          "intervals": {
            "energy": [
              {"uuid": "<INTERVAL_UUID>", "unit": 1000, "price": 0.42}
            ],
            "time": [
              {"uuid": "<INTERVAL_UUID>", "unit": 60, "price": 0.05}
            ],
            "session_fee": {
              "amount": 1.50,
              "grace_period": 300,
              "energy_threshold": 1000
            }
          },
          "marketing_texts": {
            "en_US": {
              "short_description": "Holiday rate",
              "description": "Special pricing for New Year's Day",
              "legal": ""
            }
          }
        }
      ],
      "pagination": {
        "offset": 0,
        "limit": 100,
        "next_offset": null,
        "total": 1
      }
    }

.. note::

   ``intervals.energy`` and ``intervals.time`` are **scoped to the \
   schedule entry only** — the base cost-rate intervals are not folded \
   in. An entry with no entry-scoped intervals returns empty lists.

.. note::

   ``intervals.session_fee`` is ``null`` when the entry has no session \
   fee attached. When attached, ``amount`` is in the cost rate's \
   currency, ``grace_period`` is in seconds and ``energy_threshold`` \
   is in Wh.

**Error responses**

- ``404``: Cost rate not found.

.. code-block:: json

    {
      "status": "error",
      "message": "Cost rate not found"
    }

- ``400``: Validation error — cost rate does not have \
  dynamic_pricing = 2, ``to <= from``, or one of ``from`` / ``to`` is \
  not a valid ISO-8601 datetime with an explicit timezone.

.. code-block:: json

    {
      "status": "error",
      "message": "<validation message>"
    }

- ``500``: Generic server error.

.. code-block:: json

    {
      "status": "error",
      "message": "Internal Server Error"
    }