Get Recurring Pricing Schedule Entries

Retrieve a paginated list of recurring pricing schedule entries for a cost rate, optionally filtered to a weekday + time-of-day window. The cost rate must have dynamic_pricing set to 1 (recurring per weekday — see Dynamic pricing modes).

Each entry carries its full pricing payload — validity (the list of weekday/time-range pairs that make up the schedule), intervals (energy + time + session fee, scoped to the entry only) and marketing_texts (locale-keyed, resolved with field-level fallback from the cost rate).

The window is interpreted in minute-of-week space and wraps Sunday night to Monday morning when to_* evaluates to an earlier point than from_* (e.g. from_weekday=5&from_time=22:00 together with to_weekday=1&to_time=06:00 matches entries running Fri 22:00 through Mon 06:00).

Request

• Method: GET

• Path: /api/dynamic_pricing/recurring_schedule/{cost_rate_uuid}

Path parameters

Name	Type	Description
cost_rate_uuid	string	UUID of the cost rate. Must have dynamic_pricing set to 1 (recurring per weekday).

Query parameters

Name	Type	Description
from_weekday	integer|null	Optional. 0 = Sunday, 6 = Saturday. Must be paired with from_time (half-present returns 400).
from_time	string|null	Optional. HH:MM 24-hour format. Must be paired with from_weekday.
to_weekday	integer|null	Optional. Same range as from_weekday. Must be paired with to_time. If omitted while from_* is given, defaults to end-of-day of from (from_weekday with 23:59); the window is then closed at the end of the from weekday and does not wrap to the following week.
to_time	string|null	Optional. HH:MM 24-hour format. Must be paired with to_weekday.
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.

Omitting all four from_* / to_* parameters returns every recurring schedule entry on the cost rate.

Example request

curl --location --request GET \
  'https://example.beenergised.cloud/api/dynamic_pricing/recurring_schedule/<COST_RATE_UUID>?from_weekday=1&from_time=18:00&to_weekday=1&to_time=22:00&offset=0&limit=100' \
  --header 'x-api-token: <your_token>'

Response (200)

{
  "data": [
    {
      "uuid": "<SCHEDULE_UUID>",
      "name": "Weekday Evening Peak",
      "validity": {
        "type": "recurring",
        "weekdays": [
          {
            "uuid": "<SLOT_UUID>",
            "weekday": 1,
            "weekday_name": "MON",
            "start_time": "18:00",
            "end_time": "22:00"
          },
          {
            "uuid": "<SLOT_UUID>",
            "weekday": 2,
            "weekday_name": "TUE",
            "start_time": "18:00",
            "end_time": "22:00"
          }
        ]
      },
      "intervals": {
        "energy": [
          {"uuid": "<INTERVAL_UUID>", "unit": 1000, "price": 0.55}
        ],
        "time": [],
        "session_fee": null
      },
      "marketing_texts": {
        "en_US": {
          "short_description": "Peak weekday evenings",
          "description": "Higher rate Mon-Tue 18:00-22:00",
          "legal": ""
        }
      }
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 100,
    "next_offset": null,
    "total": 1
  }
}

Note

validity.weekdays is a list — a single recurring schedule entry can carry different time windows on different weekdays, so the per-weekday shape is a list of objects rather than a single shared start_time / end_time. weekday_name is the 3-letter uppercase label (SUN … SAT).

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 of a given kind returns an empty list for that kind.

Error responses

• 404: Cost rate not found.

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

• 400: Validation error — cost rate does not have dynamic_pricing = 1, one of from_weekday / from_time (or to_weekday / to_time) is given without its pair, weekday is outside 0-6, or time is not in HH:MM 24-hour format.

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

• 500: Generic server error.

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