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

# Settlement

> How Flatpeak verifies delivery from meter records, and how you approve, pay and mark rewards paid.

Flatpeak settles on a declared commitment and metered delivery.

* The commitment is declared before the window: a [VPP event](/docs/fleet-api/guides/dispatch/vpp-events.md) share, or a [plan](/docs/fleet-api/guides/dispatch/plans.md) under a managed tariff.
* Delivery is measured from the device's [meter records](/docs/fleet-api/guides/devices.md#meter-records), never from what the OEM confirmed.

## Delivered energy

Each delivery carries the two numbers you settle on.

| Field | Rule |
| :- | :- |
| `delivered_energy_kwh` | Energy over the intervals the device's meter records cover in full, to three decimals. It keeps the sign of the delivery: negative for export |
| `coverage` | The share of the window the records cover. An interval with gaps is left out of `delivered_energy_kwh` until late records fill it |

```json theme={"system"}
{
  "committed_energy_kwh": -6.0,
  "delivered_energy_kwh": -6.0,
  "coverage": 1,
  "fulfillment": 1
}
```

The device exported 6.0 kWh over the window and its records cover all of it, so 6.0 kWh is delivered and `fulfillment` is 1.

To recompute the figure, take the device meter records that the settlement evidence [export](/docs/fleet-api/guides/settle/exports.md) carries with each delivery.

Before the window, `commitment_confidence` shows the risk. After it, settle when `coverage` reaches 1.

## Rewards

The ledger records what you owe each customer. Flatpeak keeps it and shows it to the customer but does not move money.

Entries are priced from the `terms` the enrollment joined with, one entry per reward in `terms.rewards`. Each starts with `status` `ACCRUED` and carries the `basis` and `rate` it was priced from:

| `basis` | `amount` |
| :- | :- |
| `FIXED` | `rate` for each calendar `period`, pro-rated by the days the enrollment was `ACTIVE` |
| `EVENT` | `rate`, for each event the device delivers in full |
| `DELIVERED_KWH` | The absolute value of `delivered_energy_kwh` multiplied by `rate` |
| `COMMITTED_KWH` | The absolute value of `committed_energy_kwh`, the device's locked share of an event, multiplied by `rate`, whatever the device then delivers. Nothing for a commitment the customer opted out of |

A reward is positive whichever way the energy flowed. A change to the program's `terms` does not reprice the entries of existing enrollments.

| `status` | Meaning | Next |
| :- | :- | :- |
| `ACCRUED` | Provisional. The amount can still change as late meter records arrive | [Approve rewards](/docs/fleet-api/reference/rewards/approve.md) |
| `APPROVED` | Owed to the customer. The amount is fixed | Pay the customer, then [mark rewards paid](/docs/fleet-api/reference/rewards/mark-paid.md) with your `payment_reference` |
| `PAID` | Paid, with `payment_reference` and `time_paid` | Final |

Approval fixes the amount: meter records that arrive afterwards do not change an approved entry. Approve once the delivery's `coverage` has reached 1, when nothing more is expected.

Both calls take either a list of `reward_ids` or a `filter` on program, device and period. Use `reward_ids` with a single ID to approve or pay one entry at a time, each payment with its own `payment_reference`. Use a `filter` to act on every matching entry at once: a month of rewards for a whole program is one call. Each returns the number of entries it changed, and changes only entries in the right status, so a retry is safe. Neither call fires `reward.update`, which is for entries Flatpeak creates or recalculates.

Pay through your own rails: cash, bank transfer or bill credit.

Read the ledger with [list all rewards](/docs/fleet-api/reference/rewards/list.md), filtered by program, device, period or `status`: `ACCRUED` lists what awaits your approval. An entry for an event names it in `vpp_event_id`. The customer sees each entry and its status in the OEM's app and in Connect.

## Evidence

[Exports](/docs/fleet-api/guides/settle/exports.md) package deliveries, meter records and consent records into files for a counterparty. For one device, [retrieve consent history](/docs/fleet-api/reference/devices/consent-history.md) returns every grant and revocation behind its `consent_scopes`.


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