Charge an exact amount - Amps AI Documentation

Push charge with an energy amount, such as 20 kWh for a guest or a prepaid top-up, and the charger stops the session when it has delivered it. The charger’s own meter enforces the stop, so only chargers that declare energy accept it.

1. Check the device supports it

curl https://api.amps.ai/ev-charger/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY"

{
  "success": true,
  "data": {
    "id": "device_abc123",
    "commands": {
      "charge": {
        "parameters": {
          "power": { "unit": "kw", "min": 1.4, "max": 22, "step": 0.1 },
          "energy": { "unit": "kwh", "min": 1, "max": 100 }
        },
        "execution": ["immediate", "scheduled", "windowed"]
      }
    }
  }
}

No energy key means the charger can’t meter the stop. Use target in percent if it declares that, or push charge, watch state.sessionEnergy, and push idle yourself.

2. Send the command

Deliver 20 kWh at no more than 7.4 kW:

curl -X POST https://api.amps.ai/ev-charger/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "command": "charge",
      "parameters": {
        "energy": { "value": 20, "unit": "kwh" },
        "power": { "value": 7.4, "unit": "kw" }
      }
    }
  }'

{
  "success": true,
  "data": {
    "id": "action_XFLvi9c3FB",
    "command": "charge",
    "parameters": {
      "energy": { "value": 20, "unit": "kwh" },
      "power": { "value": 7.4, "unit": "kw" }
    },
    "state": "acknowledged"
  }
}

An amount outside min and max returns 422 PARAMETER_OUT_OF_RANGE, with the bounds in details. On a charger that doesn’t declare energy you get 422 DEVICE_NOT_CAPABLE, and details.deviceCapabilities.supportedParameters lists what it does take.

{
  "success": false,
  "error": {
    "code": "PARAMETER_OUT_OF_RANGE",
    "message": "One or more parameters are outside the supported range.",
    "details": { "parameter": "energy", "value": 150, "min": 1, "max": 100, "unit": "kwh" }
  }
}

3. Confirm

The action reaches completed once the charger accepts the command and starts the session, not when 20 kWh have arrived. Poll the device and watch state.sessionEnergy climb. When isCharging turns false with sessionEnergy at the amount, the charger has delivered it. For the finished total, see Read session history.

Next steps

Start and stop a session

Charge now, pause, or charge inside a time window.

Read session history

What each session delivered, and how it was measured.