> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# VPP events

> Commit devices to a power target with a VPP event, then track allocation and delivery.

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](/docs/fleet-api/guides/dispatch/plans.md).

1. Check the group's [capacity forecast](/docs/fleet-api/guides/organize/groups-and-zones.md#capacity), then create the event.
2. Flatpeak allocates the target within each device's limits, settings and consent.
3. Each OEM fetches its shares, applies them and confirms.
4. `vpp_event.update` fires on every status change.
5. Read deliveries as meter records arrive.

## Create a VPP event

```json Request body theme={"system"}
{
  "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](/docs/fleet-api/guides/organize/groups-and-zones.md) 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](/docs/fleet-api/reference/vpp-events/create.md) 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](/docs/fleet-api/reference/vpp-events/cancel.md). 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](/docs/fleet-api/reference/vpp-events/list-devices.md) 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](/docs/fleet-api/reference/vpp-events/list-device-deliveries.md) 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](/docs/fleet-api/guides/organize/groups-and-zones.md#capacity). To settle, see [settlement](/docs/fleet-api/guides/settle/settlement.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.