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 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. Each entry’s validity.end is the next entry that starts the same day, or 23:59:59 of its own day. Only configured entries are listed: the cost rate’s default price applies wherever they leave the calendar uncovered, and the current-entry endpoints report it.

• 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). The cost rate’s weekly timeline is walked in minute-of-week order from the window immediately after the anchor, wrapping at end-of-week, and every window is returned in that order as its own entry. A configured slot carries that slot alone in validity.weekdays; the gaps around and between the slots come back priced at the cost rate’s default price. Each entry’s uuid is the parent recurring schedule’s, so it names the price identity rather than the slot — the slot is identified by validity.weekdays[].uuid.

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

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

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

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

{
  "data": [
    {
      "uuid": "<SCHEDULE_UUID>",
      "name": "Spring Sale",
      "validity": {
        "type": "unique",
        "start": "2026-04-01T00:00:00",
        "end": "2026-04-01T23:59:59"
      },
      "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

{
  "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).

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

{
  "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.

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

• 500: Generic server error.

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