VPP events

A VPP event commits a group of devices to one power target per interval. Flatpeak splits the target across the devices, sends each share to its OEM as an instruction, and records delivery per device. To run one device under a managed tariff, use a plan.

Check the group’s capacity forecast, then create the event.
Flatpeak allocates the target within each device’s limits, settings and consent.
Each OEM fetches its shares, applies them and confirms.
vpp_event.update fires on every status change.
Read deliveries as meter records arrive.

Create a VPP event

Request body

{
  "reference_id": "NG-DFS-2026-08-04-EV17",
  "intervals": [
    { "start_time": "2026-08-04T20:14:00Z", "end_time": "2026-08-04T21:00:00Z", "power_kw": -4800 },
    { "start_time": "2026-08-04T21:00:00Z", "end_time": "2026-08-04T22:00:00Z", "power_kw": -3200 }
  ],
  "group_id": "grp_2f6a9c1d8e3b5a7c4d0e9f1a"
}

Field	What it sets
`group_id`	The group to dispatch. Required
`intervals`	Ordered windows, each with a signed `power_kw` for the whole group: positive is import and negative is export
`reference_id`	Your reference, unique per account. A duplicate returns `409`, so a retry is safe

Create a VPP event with these fields. The event takes every device that is in the group at that moment, and the list is then fixed: devices that join or leave the group later do not change the event. To dispatch one program, use a group that filters on program_id; to dispatch a few chosen devices, put them in a group with an explicit list. Each device is dispatched under its own enrollment’s terms, including its program’s opt-out policy and rewards.

Allocation

Flatpeak allocates the target across the event’s devices, within each device’s limits, and may rebalance the shares until time_allocation_locks. Some devices in the event get no share: one cut by the customer’s settings or by its condition, or one whose enrollment is not ACTIVE. Such a device stays in the event, is recorded as NOT_COMMITTED, and does not count against fulfillment.

`status`	Meaning
`ALLOCATION_OPEN`	Shares can still change
`LOCKED`	Shares are fixed
`ACTIVE`	The window is running
`COMPLETE`	The window has ended
`CANCELED`	You called it off

To call an event off, cancel a VPP event. Before the window the event is withdrawn whole; during it, commitments end at cancel time and delivery is scored up to that point.

Delivery

The event carries the result for the whole group in delivery: requested, committed and delivered power and energy, and fulfillment. device_count is the number of devices it took from the group. List all VPP event devices returns one compact row per device in the event, including those with no share: its status, committed and delivered energy, and fulfillment. Filter by status to pull only the devices that fell short, such as ZERO or UNREPORTED. Delivery is measured from meter records only; the OEM’s confirmation shows intent.

`fulfillment`	Meaning
`1`	The full window at the committed power
A fraction	Partial delivery
`0`	Metered, nothing delivered
`null`	No meter records cover the window

For one device’s full record, list device deliveries with vpp_event_id returns a row per interval:

When	Read	It tells you
Before the window	`commitment_confidence`	How likely the device is to deliver, from 0 to 1
After the window	`coverage`	How much of the window the meter records cover
After the window	`delivered_energy_kwh`	The energy you settle on. It counts only fully covered intervals, so it rises as late records arrive

Settle when coverage reaches 1. A commitment stands whatever the device does: a deviation is recorded, and the commitment is not canceled. For what a group can deliver next, read its capacity forecast. To settle, see settlement.

Get started

Enroll customers

Devices

Tariffs

Dispatch devices

Settle and reward

Platform

Create a VPP event

Allocation

Delivery