<aside> 💡

TL;DR: solar-aware charging needs accurate vehicle metadata (battery capacity, max charge power) and accurate inverter metadata (peak power, azimuth, tilt, cut-in threshold, base load). Both are set via the same device PATCH endpoint, one device at a time. Finally, the vehicle's policy must be switched to CHARGE BY FORECAST to activate the feature.

</aside>

For the feature overview and the data each side must provide, see Solar-Aware Charge Planning. This page covers the API mechanics — which fields you set on which device, what the valid ranges are, and how to verify the values you sent.

The endpoint and authentication pattern are the same as the existing device PATCH described in Gridio Connect API Endpoints and Device status and control:

curl -X PATCH <https://api.gridio.energy/api/v1/businesses/{business_id}/devices/{dev_id}> \
  -H "Authorization: Bearer <backend access token>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

All fields below are optional — include only the ones you want to change in the request body, the rest retain their previous value.

🚗 Vehicle settings

Set these on a device of type Electric vehicle. When the underlying integration does not report the value (e.g. some OEMs don't expose battery capacity through their API), Gridio applies a default so smart charging still works; supplying the real value produces more accurate plans.

Parameter Required for solar-aware Description Data type Range Default if omitted Example value
max_capacity Recommended Battery capacity in watt-hours (Wh). Caps how much energy any plan can target. int / float 1 000 – 300 000 (1 kWh – 300 kWh) 80 000 (80 kWh) 77 000
max_charge_power Recommended Maximum charge power in watts (W). Caps how much solar power per hour Gridio credits towards the vehicle. int / float 1 000 – 350 000 (1 kW – 350 kW) 7 200 (7.2 kW) 11 000

Example — setting vehicle battery + charging characteristics

curl -X PATCH <https://api.gridio.energy/api/v1/businesses/{business_id}/devices/{dev_id}> \
  -H "Authorization: Bearer <backend access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "max_capacity": 77000,
    "max_charge_power": 11000
  }'

A 200 response and an empty body indicate success.

🔆 Activating solar-aware planning — set the policy to CHARGE BY FORECAST

Configuring the vehicle and inverter metadata above is necessary but not sufficient: solar-aware planning only engages once the vehicle's charging policy is switched from the default CHARGE BY to CHARGE BY FORECAST. Until then the vehicle keeps charging on its regular price-optimized plan and ignores the next-day solar forecast.

Set it on the Electric vehicle device via the same PATCH endpoint:

curl -X PATCH <https://api.gridio.energy/api/v1/businesses/{business_id}/devices/{dev_id}> \
  -H "Authorization: Bearer <backend access token>" \
  -H "Content-Type: application/json" \
  -d '{ "policy": "CHARGE BY FORECAST" }'
policy value Meaning
CHARGE BY (default) Regular price-optimized charging; the solar forecast is not used.
CHARGE BY FORECAST Solar-aware planning is active — the next-day PV forecast feeds the overnight charge plan.

Confirm it took effect by reading the device back (see Verifying the values you set below): the policy field should read CHARGE BY FORECAST.

☀️ Inverter (PV) settings