Get Next Pricing Schedule Entries
----------------------------------

Retrieve a paginated list of pricing schedule entries that come \
**strictly after** a given anchor entry on a cost rate. The URL is the \
same for both dynamic-pricing modes — the service branches on the \
cost rate's ``dynamic_pricing`` value (see \
:ref:`dynamic-pricing-modes`) and returns entries of the matching \
shape.

The anchor entry itself is **not** included in the response.

- **dynamic_pricing = 2 (exact date and time):** the anchor is a \
  ``unique_pricing_config`` UUID; entries are returned ordered by \
  ``start`` ascending, starting from the first entry whose ``start`` \
  is strictly greater than the anchor's.
- **dynamic_pricing = 1 (recurring per weekday):** the anchor is a \
  single weekday/time slot UUID (a ``rate_cost_schedule_config`` row, \
  not the parent recurring schedule). Slots are walked in \
  minute-of-week order starting from the slot immediately after the \
  anchor, **wrapping at end-of-week**, and each parent recurring \
  schedule is collected on first encounter (the response contains \
  parent schedules, not individual slots).

Each returned entry carries the same full payload as the other \
schedule endpoints — ``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/next_schedule/{cost_rate_uuid}/{schedule_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 \
       ``1`` or ``2``; static cost rates (``dynamic_pricing = 0``) \
       return ``400``.
   * - schedule_uuid
     - string
     - Anchor entry UUID. For dynamic_pricing = 2, the UUID of a \
       ``unique_pricing_config``. For dynamic_pricing = 1, the UUID \
       of a single weekday/time slot (a ``rate_cost_schedule_config``, \
       the child of a recurring schedule). Must belong to \
       ``cost_rate_uuid`` on the calling mandant; mismatches return \
       ``404``.

**Query parameters**

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

   * - Name
     - Type
     - Description
   * - 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/next_schedule/<COST_RATE_UUID>/<SCHEDULE_UUID>?offset=0&limit=100' \
      --header 'x-api-token: <your_token>'

**Response (200) — dynamic_pricing = 2 anchor**

.. code-block:: json

    {
      "data": [
        {
          "uuid": "<SCHEDULE_UUID>",
          "name": "Spring Sale",
          "validity": {
            "type": "unique",
            "start": "2026-04-01T00:00:00Z"
          },
          "intervals": {
            "energy": [
              {"uuid": "<INTERVAL_UUID>", "unit": 1000, "price": 0.38}
            ],
            "time": [],
            "session_fee": null
          },
          "marketing_texts": {
            "en_US": {
              "short_description": "Spring sale",
              "description": "Reduced energy rate for April",
              "legal": ""
            }
          }
        }
      ],
      "pagination": {
        "offset": 0,
        "limit": 100,
        "next_offset": null,
        "total": 1
      }
    }

**Response (200) — dynamic_pricing = 1 anchor**

.. code-block:: json

    {
      "data": [
        {
          "uuid": "<SCHEDULE_UUID>",
          "name": "Weekend Daytime",
          "validity": {
            "type": "recurring",
            "weekdays": [
              {
                "uuid": "<SLOT_UUID>",
                "weekday": 0,
                "weekday_name": "SUN",
                "start_time": "09:00",
                "end_time": "18:00"
              },
              {
                "uuid": "<SLOT_UUID>",
                "weekday": 6,
                "weekday_name": "SAT",
                "start_time": "09:00",
                "end_time": "18:00"
              }
            ]
          },
          "intervals": {
            "energy": [
              {"uuid": "<INTERVAL_UUID>", "unit": 1000, "price": 0.42}
            ],
            "time": [],
            "session_fee": null
          },
          "marketing_texts": {
            "en_US": {
              "short_description": "Weekend daytime",
              "description": "Standard rate Sat/Sun 09:00-18:00",
              "legal": ""
            }
          }
        }
      ],
      "pagination": {
        "offset": 0,
        "limit": 100,
        "next_offset": null,
        "total": 1
      }
    }

.. note::

   To page through the results, pass the previous response's \
   ``pagination.next_offset`` as the next request's ``?offset=``. \
   ``next_offset`` is ``null`` on the last page.

**Error responses**

- ``404``: Cost rate not found, or the anchor ``schedule_uuid`` does \
  not exist on the given cost rate (including cross-cost-rate or \
  cross-mandant anchors).

.. code-block:: json

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

.. code-block:: json

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

- ``400``: The cost rate is static (dynamic_pricing = 0) — \
  ``next_schedule`` is only valid for dynamic-pricing cost rates. \
  Any other validation error on a query parameter is surfaced with \
  the same status code and ``<validation message>`` body.

.. code-block:: json

    {
      "status": "error",
      "message": "Cost rate is static; next_schedule is only valid for dynamic-pricing cost rates"
    }

- ``500``: Generic server error.

.. code-block:: json

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