Skip to main content
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. 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 and list all zones.

Delivery loop

  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 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. 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, 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 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. 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

Delivery record

List device deliveries 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, or the Connect Rewards page. The VPP operator pays the rewards, and Flatpeak keeps the ledger.