Programs

A program is your offer to customers. In a VPP program the customer keeps their tariff and earns from grid events. In a managed tariff you supply the energy and run the device. Customers enroll in your app or in their OEM’s app.

Create

Call create a VPP program. The program starts in DRAFT, private to you. display_name, currency_code and estimate are required.

{
  "display_name": "Community Powershare",
  "description": "Earn from grid events while you keep your tariff.",
  "url": "https://pick.com/programs/community-powershare",
  "managed": false,
  "listed": true,
  "currency_code": "USD",
  "estimate": {
    "amount": 612,
    "period": "YEAR",
    "dispatch_events_per_month": 15
  },
  "terms": {
    "rewards": [
      { "basis": "FIXED", "rate": 15, "period": "QUARTER" },
      { "basis": "DELIVERED_KWH", "rate": 0.35 }
    ],
    "opt_out_policy": "ALLOWED",
    "notice_days": 30
  },
  "eligibility": {
    "oem_ids": ["oem_6a3a8dada72cd0a249ff9528"],
    "device_types": ["BATTERY_STORAGE"],
    "min_storage_capacity_kwh": 5,
    "min_export_power_kw": 3,
    "telemetry_requirements": {
      "state_interval_seconds": 300,
      "device_meter_interval_seconds": 900
    }
  },
  "enrollment": {
    "join_days": 10,
    "approval_required": false,
    "dispatch_test_required": true
  }
}

Group	What goes in
Top level	What the program is: its name and copy, `managed`, `listed` and `currency_code`
`estimate`	What the customer is told to expect. A projection, never binding
`terms`	What binds both sides once the customer has joined
`eligibility`	Which devices can join
`enrollment`	How a device gets in

currency_code is the currency of estimate.amount and of every reward rate. Set it on create, because it cannot be changed afterwards.

Estimate

estimate is the figure the customer sees before they join: amount for one period (YEAR or MONTH), and optionally the dispatch_events_per_month it assumes. The copy follows managed: bill savings for a managed tariff, earnings otherwise.

Terms

terms holds what you and the customer are bound by after they join.

Field	What it sets
`rewards`	What you pay. See Rewards
`opt_out_policy`	`ALLOWED`, `ALLOWED_BEFORE_LOCK` (until the allocation locks at `time_allocation_locks`) or `NOT_ALLOWED`. Opted-out commitments show as `OPTED_OUT` and do not count as failures
`notice_days`	The longest leaving may take once the customer is enrolled. A request to leave that you have not approved ends after this many days

The enrollment keeps a copy of the terms it joined with. A change to terms applies only to enrollments made after it.

Rewards

Each entry in rewards has a basis and a rate, in the program’s currency_code. A basis appears at most once.

`basis`	`rate` is paid	Extra field
`FIXED`	Once per `period`	`period`: `MONTH`, `QUARTER` or `YEAR`, required
`EVENT`	Per event the device delivers in full
`DELIVERED_KWH`	Per kWh delivered, from the device’s meter records
`COMMITTED_KWH`	Per kWh of the device’s locked share of an event

A FIXED reward follows calendar periods, pro-rated by the days the enrollment is ACTIVE.
COMMITTED_KWH pays whatever the device then delivers, and nothing for a commitment the customer opted out of.
A listed VPP program needs at least one reward before it can go LIVE (422 terms_required). A managed tariff may have none.

Eligibility

eligibility decides which devices are offered the program: oem_ids, device_types, an optional zone_id, and the minimums min_storage_capacity_kwh and min_export_power_kw. Omit oem_ids to enable every OEM on your account. telemetry_requirements sets the sampling a device must sustain, with a minimum of 60 seconds.

Field	What it sets
`state_interval_seconds`	How often the device samples its state
`device_meter_interval_seconds`	How finely the device meters its own flows. Required, because every program settles on device meter records

While its state is unchanged, a device sends a heartbeat. Flatpeak sets the heartbeat at three times state_interval_seconds, and never below 300 seconds. Each OEM declares the finest sampling its fleet can sustain. A program that samples finer is not offered to that OEM’s devices.

Enrollment settings

Field	What it sets
`join_days`	The longest enrollment may take after the customer asks to join
`approval_required`	`true` holds every enrollment for your decision
`dispatch_test_required`	`true` (default): each device delivers a short `TEST` event before approval. `false` skips it
`signup_url`	Where a customer signs up for a listed managed tariff. See Sign-up from an OEM app

Managed tariffs

With a managed tariff you supply the electricity and run the device with plans. Plans are accepted only under a managed program.

Set managed to true. Your account must be set up to supply energy.
When a customer joins, your tariff replaces theirs. Create it as a device tariff, with the enrolled device’s device_id and location_id.

A managed tariff needs no rewards, so the smallest one is:

{
  "display_name": "Phase Flex",
  "managed": true,
  "currency_code": "USD",
  "estimate": { "amount": 104, "period": "MONTH" },
  "enrollment": { "signup_url": "https://phase.com/tariffs/flex/signup" }
}

You can offer several managed tariffs. A listed managed tariff appears on the OEM app’s Programs page, and the customer signs up for it on your site. Consent is the last step, after the customer has read your offer and signed up.

Set enrollment.signup_url to your sign-up page. A listed managed program cannot go LIVE without it (422 signup_url_required).
The customer chooses your tariff in the OEM app, and Flatpeak opens that URL with three query parameters. At this point you hold no consent, no enrollment and no device.
https://phase.com/tariffs/flex/signup?program_id=vpr_5c8d1f2a7b3e4d6c9a0f1b2c&oem_id=oem_6a3a8dada72cd0a249ff9528&signup_reference=sur_6a7c0e2f9b4d1a3c5e8f7b6d
Sign the customer up, and keep the three values with their record.
Create a Connect session with the same oem_id and program_id, add signup_reference, and open target_url as in Connect. The OEM app opens Connect on the device the customer started from, so they do not pick it again.
The customer grants consent and Flatpeak creates the enrollment. On device.connect, create the tariff for the device, which clears the AWAITING_TARIFF step.

A signup_reference works once, for 30 days. It identifies nobody on its own: the device reaches you only after the customer signs in to the OEM app and consents. If the reference is missing, used or expired (422 signup_reference_invalid), create the session without it, and the customer picks the device in the OEM app. An unlisted managed tariff needs no enrollment.signup_url: the customer starts in your app.

Publish

Request LIVE with update a VPP program. program.update fires on every status change.

Program	What happens
Unlisted	Goes `LIVE` at once. Customers enroll only from your app, with `program_id` on the Connect session
Listed	Moves to `PENDING_APPROVAL`. Each OEM in `eligibility` approves it, then it is `LIVE` and appears on the OEM app’s Programs page. Managed tariffs appear under their own heading, and choosing one sends the customer to your `enrollment.signup_url`. A rejection sets `REJECTED` with the OEM’s `rejection_reason`: fix it and resubmit

PAUSED keeps enrolled devices and stops new enrollments. Editing a live program’s customer-facing copy or estimates sends it back for OEM approval. Flatpeak decides which devices see a live program, so you cannot target individual customers.

A VPP program offered to a customer in Connect — A listed program in Connect

Enrollments

Flatpeak approves an enrollment once it passes consent, tariff, telemetry and the dispatch test. With enrollment.approval_required, it waits at step AWAITING_APPROVAL for you. See Enrollment states for the lifecycle and your two actions.

To read	Use
Uptake and capacity	Program summary: `enrollment_counts` and `capacity`
Members	List all VPP enrollments, filtered by `program_id`
A program’s devices, kept current	A group that filters on `program_id`

Get started

Enroll customers

Devices

Tariffs

Dispatch devices

Settle and reward

Platform

Create

Estimate

Terms

Rewards

Eligibility

Enrollment settings

Managed tariffs

Publish

Enrollments

Create

Estimate

Terms

Rewards

Eligibility

Enrollment settings

Managed tariffs

Sign-up from an OEM app

Publish

Enrollments