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

# Dispatch

> How a VPP operator dispatches your enrolled devices: VPP events, plans, the delivery loop, allocation and the delivery record.

A VPP operator dispatches your enrolled devices through Flatpeak. You deal only with Flatpeak: it notifies you, and you fetch the instructions, apply them and confirm. Meter records prove delivery.

## VPP events and plans

Every instruction is binding, and power is signed: positive imports, negative exports.

| | VPP event | Plan |
| :- | :- | :- |
| Used by | Every program | Managed tariff programs only |
| The VPP operator sends | A power target per interval, for a group of devices | A power profile for one device |
| Reaches you as | Each device's share, as a commitment | The plan as sent |
| Webhook | `vpp_event.update`, once per event | `device.instructions.update`, per device |

A VPP event has one or more ordered intervals, each with a `power_kw` target for your fleet.

* `status` runs `ALLOCATION_OPEN`, `LOCKED`, `ACTIVE`, `COMPLETE`, or ends at `CANCELED`. At `time_allocation_locks` the event locks and each share becomes an instruction.
* The devices in an event can be in different programs, and each takes part under its own enrollment, with that enrollment's opt-out policy and rewards.
* An event is created for one of the VPP operator's groups, named by `group_id`, and takes the devices that were in the group at that moment. Groups and zones belong to the VPP operator, but you can read them for your devices with [list all groups](/docs/energy-api/reference/groups/list.md) and [list all zones](/docs/energy-api/reference/zones/list.md).

## Delivery loop

```mermaid actions={false} theme={"system"}
sequenceDiagram
    participant OP as VPP operator
    participant FP as Flatpeak
    participant YOU as Your backend
    participant DEV as Device

    OP->>FP: 1. VPP event or plan
    Note over FP: Guardrails applied
    FP->>YOU: 2. Webhook
    YOU->>FP: 3. Fetch instructions
    YOU->>DEV: 4. Apply
    YOU->>FP: 5. Confirm
    DEV-->>YOU: 6. Meter records
    YOU-->>FP: 6. Meter records
    FP-->>OP: Confirmation and delivery
```

1. Receive the webhook and act at once. Your fetch-and-confirm speed is published on the device as `response_time`, and VPP operators set lead times from it.
2. Fetch the instructions. [Retrieve device instructions](/docs/energy-api/reference/instructions/retrieve.md) returns one merged timeline, up to 72 hours ahead, in which each segment names its `vpp_event_id` or `plan_id`. Where a commitment overlaps a plan, the commitment wins, so segments never overlap. For a large event, read every device's share from `allocation` on [retrieve a VPP event](/docs/energy-api/reference/vpp-events/retrieve.md). Without webhooks, poll: `data` is empty when there is nothing to follow.
3. Apply them. Keep every segment intact; outside the segments, you control the device.
4. Confirm. Send the power the device will deliver for each segment with [confirm instructions](/docs/energy-api/reference/instructions/confirm.md), passing `record_reference_id` to retry safely. Confirming less than the instruction records a deviation, and the commitment stands.
5. Meter the delivery. Submit [device state and meter records](/docs/energy-api/guides/vpp/telemetry.md) at the required interval, because delivery and rewards settle from them.

The dispatch test at enrollment step `TESTING_DISPATCH` runs this loop once with a `TEST` event.

## Allocation

Flatpeak splits each interval's target across the event's devices, and the event's `allocation` lists your devices' shares. Each share is bounded to the device's capabilities, settings and current state. Shares can change until `time_allocation_locks`; from then on each one is an instruction.

`device_count` is the number of your devices in the event. A device that is in the event but has no `allocation` row for a window was given no share for it.

## Guardrails

Flatpeak enforces these before anything reaches a device. A demand that breaks one is cut back or rejected, and the VPP operator sees why.

| Guardrail | Bound |
| :- | :- |
| Power | `ac_import_limit_kw` and `ac_export_limit_kw` in the device `capabilities` |
| Commands | At most 12 plans per device per hour |
| Settings | Energy under `backup_reserve_percent` is never dispatched. `export_rule` and `charge_from_grid_enabled` bound every instruction |
| Device condition | A device reporting `grid_status` `ISLANDED` or `storm_mode_active` `true` is not dispatched |
| Consent | Nothing is dispatched without the user's consent, given in Connect |

Intervals cut by a setting or a device condition are recorded as declined and do not count as a shortfall. On a VPP event they show as `NOT_COMMITTED` in the delivery record.

## Declining and deviating

| | Decline | Deviation |
| :- | :- | :- |
| What | The user skips one event | The device falls short for a physical reason: thermal derate, BMS fault, islanding |
| How | In Connect, on [VPP summary](/docs/energy-api/reference/connect/vpp/summary.md), where the program's `terms.opt_out_policy` allows, or from your backend with [opt out](/docs/energy-api/reference/vpp-events/opt-out.md), reversible with [opt in](/docs/energy-api/reference/vpp-events/opt-in.md) until the event locks | Deliver what is safe and confirm what the device will deliver |
| Recorded as | `OPTED_OUT`. Excluded from fulfillment scoring | `PARTIAL` or `ZERO`. Scored, and settled on what was delivered |

## Delivery record

[List device deliveries](/docs/energy-api/reference/vpp-events/list-deliveries.md) returns one row per event interval: committed power and energy, delivered energy, `coverage` and `fulfillment`, with a `status` of `FULL`, `PARTIAL`, `ZERO`, `UNREPORTED`, `OPTED_OUT` or `NOT_COMMITTED`.

* Delivered figures come from meter records only, never from the confirmation.
* `delivered_energy_kwh` is the figure rewards are priced on: the energy the device's meter records show for fully covered intervals. An interval with gaps is left out until late records fill it, and `coverage` says how much of the window the records cover.

Rewards accrue from it: [list device rewards](/docs/energy-api/reference/vpp-enrollments/list-rewards.md), or the Connect [Rewards](/docs/energy-api/reference/connect/vpp/rewards.md) page. The VPP operator pays the rewards, and Flatpeak keeps the ledger.


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