TL;DR: The device-level charge_by time gives a single ready-by deadline that applies everywhere, every day. If you need different deadlines per weekday — or different schedules at different charging locations — use the per-(device, location) charging window config described here.
This page describes the configuration surface — what you POST and how Gridio validates it. For the behaviour behind the configuration — how Gridio chooses charging hours within the window, how multi-day plug-ins are handled, how guaranteed_max_price and guaranteed_soc interact, and what an opt-out actually does to the running plan — see Smart charging logic.
This config is scoped to a single (device, location) pair. The same vehicle can have a completely different ready-by schedule at home and at the summer house — Gridio picks the config that matches the location the device is currently plugged in at. Two vehicles sharing the same household can also have different schedules.
When a per-location config is present, it overrides the static device-level fields (charge_by, charge_from) for that (device, location) pair. The static fields are not deleted — they continue to apply at any other location where no per-location config exists, and they take effect again for this location if the per-location config is removed (see the DELETE endpoint below).
You do not need to migrate existing devices: any device that has no per-location config keeps behaving exactly as before, driven by the device-level settings.
The device-level charge_by field (see Setting up smart charging) covers the common case: one ready-by time, every day, regardless of location. Use the per-location charging window when:
{
"charging_window_config": {
"charge_by": [
{ "days": ["mon", "tue", "wed", "thu", "fri"], "time": "07:00" },
{ "days": ["sat", "sun"], "time": "10:00" }
],
"opt_out_periods": [
{ "days": ["sun"], "start": "08:00", "end": "12:00" }
]
}
}
| Field | Required | Description |
|---|---|---|
charge_by |
✅ | Array of intervals. Each interval defines a ready-by time (HH:MM, device's local timezone) for one or more days of the week. At least one interval is required. |
charge_by[].days |
✅ | Days the interval applies to. Allowed values: mon, tue, wed, thu, fri, sat, sun. A given day may appear in at most one interval — no duplicates. |
charge_by[].time |
✅ | Ready-by clock time on those days, in HH:MM 24-hour format. |
opt_out_periods |
❌ | Optional array of recurring weekly windows during which Gridio is not allowed to control charging. Both bounds are inclusive. |
opt_out_periods[].days |
✅ | Days the opt-out applies to. Same allowed values as above. |
opt_out_periods[].start / .end |
✅ | Start and end clock times, HH:MM. An end of 00:00 is treated as end-of-day. The window must be non-empty and may not overlap with another opt-out window on the same day. |
Validation: A charge_by time may not fall inside an opt-out period on the same day — Gridio rejects the config with HTTP 400 if it does.
You do not need to list all seven days in charge_by. A day that is not listed in any charge_by interval has no ready-by deadline at that location — Gridio will smart-charge the vehicle across the full available price window (in practice, the next ~36 h of published spot prices) and aim only at price optimization, not at a specific finish time.
This matters in two ways that often surprise integrators migrating from the legacy device-level charge_by:
charge_by / charge_from fields are not consulted at that location, on any day. A day omitted here is not silently filled in from the legacy fields — it really has no deadline.