> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Update a VPP program > Updates a program's copy, estimates, terms or status. Requesting `LIVE` moves a listed program to `PENDING_APPROVAL` and an unlisted one straight to `LIVE`. `PAUSED` stops new enrollments, and editing a live program's customer-facing copy re-enters OEM approval. Fires `program.update`. A `listed` program with `managed` `false` needs at least one entry in `terms.rewards` before its `status` can be `LIVE`; otherwise the call returns `422` `terms_required`. A managed tariff may have none. A `listed` program with `managed` `true` needs `enrollment.signup_url`; otherwise the call returns `422` `signup_url_required`. A change to `terms` applies only to enrollments made after it, because each enrollment keeps a copy of the `terms` it joined with. ## OpenAPI ````yaml fleet-api/reference/flatpeak-api-spec-fleet.json PATCH /vpp-programs/{program_id} openapi: 3.0.3 info: description: >- The Flatpeak Fleet API. VPP operators use it to enroll, dispatch and settle OEM device fleets. ## Authentication Exchange your `account_id` and `secret_key` for a bearer token at `POST /auth/tokens` with basic auth. Send it as `Authorization: Bearer ` on every request. ## Base URL `https://fleet-api.flatpeak.com` ## Pagination Lists return `data`, `next_cursor` and `url`. Pass `next_cursor` as `cursor` until it is `null`. A cursor is opaque and bound to the endpoint and query parameters that issued it. ## Errors Every non-2xx response carries `object`, `type`, `code` and `message`. Branch on `code`. ## Money and energy Money is a decimal number paired with a `currency_code` (ISO 4217). Power is in kW and energy in kWh. Positive is import, negative is export. ## Live and test `live_mode` marks live or test data. version: 2027-01-01.busbar title: Flatpeak Fleet API termsOfService: https://flatpeak.com/legal contact: name: Technical Support email: support@flatpeak.com url: https://flatpeak.com/contact license: name: Apache 2.0 url: https://flatpeak.com/legal servers: - url: https://fleet-api.flatpeak.com security: - bearerAuth: [] tags: - name: Authentication description: >- Exchange your account credentials for a bearer token to authenticate API requests. - name: Connect description: >- Create and retrieve Connect sessions for onboarding customers through your own app. - name: OEMs description: List and retrieve the OEMs whose devices your fleet can reach. - name: Devices description: >- Retrieve, list and update the devices connected to your account, and read their consent history and shared settings. - name: Locations description: >- Read the location a device sits behind: its timezone, currency, metering and your devices there. - name: Dispatch description: Submit plans to devices on managed tariffs and read the dispatch timeline. - name: Telemetry description: Read device state, device meter records and location meter records. - name: Tariffs description: Create, retrieve, delete, and list tariffs. - name: Events description: Retrieve and list account events. - name: VPP Programs description: >- Define and manage VPP programs: the commercial terms devices enroll under, and their live state. - name: Groups description: >- Named collections of devices for bulk dispatch and aggregated reads. OEMs see them read-only as [groups](/energy-api/reference/groups/list) on the Energy API. - name: Zones description: >- Network areas resolved to devices by Flatpeak, for locational eligibility and grouping without handling addresses. - name: Exports description: >- Package settlement evidence, consent records and enrollment registers as downloadable files. - name: Rewards description: >- The reward ledger: entries accrue from delivery, you approve them, pay the customers and mark them paid. - name: VPP Enrollments description: Track and act on device enrollments across your programs. - name: VPP Events description: >- Commit market activations: create an event for a group, then read its state and its devices' results. externalDocs: description: Documentation url: https://docs.flatpeak.com paths: /vpp-programs/{program_id}: parameters: - schema: type: string name: program_id in: path required: true description: Flatpeak Program ID. patch: tags: - VPP Programs summary: Update a VPP program description: >- Updates a program's copy, estimates, terms or status. Requesting `LIVE` moves a listed program to `PENDING_APPROVAL` and an unlisted one straight to `LIVE`. `PAUSED` stops new enrollments, and editing a live program's customer-facing copy re-enters OEM approval. Fires `program.update`. A `listed` program with `managed` `false` needs at least one entry in `terms.rewards` before its `status` can be `LIVE`; otherwise the call returns `422` `terms_required`. A managed tariff may have none. A `listed` program with `managed` `true` needs `enrollment.signup_url`; otherwise the call returns `422` `signup_url_required`. A change to `terms` applies only to enrollments made after it, because each enrollment keeps a copy of the `terms` it joined with. operationId: update-a-vpp-program parameters: [] requestBody: $ref: '#/components/requestBodies/ProgramUpdate' responses: '200': $ref: '#/components/responses/Program' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '422': $ref: '#/components/responses/422' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' components: requestBodies: ProgramUpdate: description: Program fields to update. required: true content: application/json: schema: $ref: '#/components/schemas/ProgramUpdate' responses: '400': description: >- 400 Bad Request: the request was malformed or a required field is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: '401 Unauthorized: authentication credentials are missing or invalid.' content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: '403 Forbidden: you do not have permission to access this resource.' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '404 Not Found: the requested resource does not exist.' content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- 422 Unprocessable Entity: the request is well-formed but cannot be processed, for example missing required data. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '429 Too Many Requests: the rate limit has been exceeded.' content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: >- 500 Internal Server Error: an unexpected error occurred. Safe to retry with backoff. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- 503 Service Unavailable: the service is temporarily down for maintenance. Retry after the indicated delay. content: application/json: schema: $ref: '#/components/schemas/Error' Program: description: Program response. content: application/json: schema: $ref: '#/components/schemas/Program' example: id: vpr_5c8d1f2a7b3e4d6c9a0f1b2c object: vpp_program live_mode: true 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 zone_id: null 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 signup_url: null status: LIVE rejection_reason: null time_created: '2026-08-12T09:30:00Z' account_id: acc_6a5e504c3b98d0d6739b5f72 schemas: ProgramUpdate: title: ProgramUpdate type: object description: >- Fields to change on a program. All optional; omitted fields keep their value. `currency_code` cannot be changed. properties: display_name: type: string description: Program name shown to customers. example: Community Powershare description: type: string description: Short description shown to customers at enrollment. example: Earn from grid events while you keep your tariff. url: type: string nullable: true description: Public page with program details. example: https://pick.com/programs/community-powershare managed: type: boolean default: false example: false description: >- `true` for a managed tariff: you run the device under this program with [plans](/fleet-api/reference/plans/submit), and it replaces the customer's tariff. Plans are accepted only for devices enrolled in a managed program. Any number of programs can be managed. listed: type: boolean default: true example: true description: >- `true` to offer the program in OEM apps to eligible devices. Listing requires OEM approval, tracked by `status`. A program that is not listed goes `LIVE` without approval and is reachable only from your own app with `program_id` on the Connect session. estimate: type: object description: >- What the customer is told to expect before they join. It is a projection and never binding. The copy follows `managed`: bill savings for a managed tariff, earnings otherwise. required: - amount - period properties: amount: type: number example: 612 description: >- Estimated amount for one `period`, in the program's `currency_code`, in large currency units: bill savings when `managed` is `true`, earnings otherwise. period: type: string enum: - YEAR - MONTH example: YEAR description: Period the estimate covers. dispatch_events_per_month: type: number minimum: 0 example: 15 description: Approximate number of VPP events per month the estimate assumes. terms: type: object description: >- What binds you and the customer once they have joined: what you pay, whether they may skip events, and how long leaving takes. The enrollment keeps a copy of the `terms` it joined with, so a change applies only to later enrollments. properties: rewards: type: array description: >- What the customer is paid. Each `basis` appears at most once. A `listed` program with `managed` `false` needs at least one reward before its `status` can be `LIVE`. A managed tariff may have none. example: - basis: FIXED rate: 15 period: QUARTER - basis: DELIVERED_KWH rate: 0.35 items: type: object required: - basis - rate properties: basis: type: string enum: - FIXED - EVENT - DELIVERED_KWH - COMMITTED_KWH example: DELIVERED_KWH description: >- What `rate` is paid for. | Value | `rate` is paid | | :--- | :--- | | `FIXED` | Once per `period`, by calendar period, pro-rated by the days the enrollment is `ACTIVE` | | `EVENT` | Per VPP 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 a VPP event, whatever the device then delivers. Nothing for a commitment the customer opted out of | rate: type: number example: 0.35 description: >- Amount paid per unit of `basis`, in the program's `currency_code`, in large currency units. period: type: string enum: - MONTH - QUARTER - YEAR example: QUARTER description: >- Period a `FIXED` reward is paid for. Required when `basis` is `FIXED`, and not used otherwise. opt_out_policy: type: string enum: - ALLOWED - ALLOWED_BEFORE_LOCK - NOT_ALLOWED example: ALLOWED description: >- Whether customers may skip individual VPP events. | Value | Meaning | | :--- | :--- | | `ALLOWED` | Default. Any scheduled or active VPP event. Skipped intervals are recorded as `OPTED_OUT`. | | `ALLOWED_BEFORE_LOCK` | Only until the allocation locks. | | `NOT_ALLOWED` | No per-event opt-out. Customers can still unenroll. | default: ALLOWED notice_days: type: integer example: 30 description: >- Maximum number of days leaving may take once the customer is enrolled. A request to leave that you have not approved ends after this many days. Shown to the customer before they join and when they leave. eligibility: type: object description: Which devices can join the program. properties: oem_ids: type: array items: type: string description: >- [OEM IDs](/fleet-api/reference/oems/list) the program is enabled for. Omit to enable it for every OEM available to your account. example: - oem_6a3a8dada72cd0a249ff9528 device_types: type: array items: type: string enum: - BATTERY_STORAGE - ELECTRIC_VEHICLE - EV_CHARGER - PV_SYSTEM - OTHER description: Device types the program accepts. example: - BATTERY_STORAGE zone_id: type: string nullable: true description: >- Restrict eligibility to a [network zone](/fleet-api/reference/zones/retrieve). min_storage_capacity_kwh: type: number nullable: true example: 5 description: >- Minimum usable storage capacity, in kWh, for a device to qualify. min_export_power_kw: type: number nullable: true example: 3 description: Minimum export power, in kW, a device must support to qualify. telemetry_requirements: type: object description: >- Telemetry the program requires from enrolled devices. A program that samples finer than an OEM's fleet can sustain is not offered to that OEM's devices. Omit the group to use Flatpeak's default intervals. required: - device_meter_interval_seconds properties: state_interval_seconds: type: integer minimum: 60 example: 300 description: >- Sampling interval for device state, in seconds, minimum 60. A sample is due when the interval has elapsed and a signal changed. While nothing changes the device sends a heartbeat, which Flatpeak sets at three times this interval and never below 300 seconds. Feed health (`state_data_delayed`) is judged against the heartbeat. device_meter_interval_seconds: type: integer minimum: 60 example: 900 description: >- Sampling interval for the device's own meter records, in seconds, minimum 60. Required, because every program settles on device meter records. Delivery cadence is separate. enrollment: type: object description: How a device gets in. properties: join_days: type: integer example: 10 description: >- Maximum number of days enrollment may take after the customer asks to join. Shown to the customer before they join. approval_required: type: boolean default: false example: false description: >- When `true`, each enrollment waits at `AWAITING_APPROVAL`, after the dispatch test, for your decision: approve it, or unenroll it to turn it down. When `false`, Flatpeak approves it. dispatch_test_required: type: boolean default: true example: true description: >- When `true`, the default, Flatpeak issues a `TEST` VPP event during enrollment, and the device must deliver it to pass. When `false`, the step is skipped. signup_url: type: string nullable: true example: https://phase.com/tariffs/flex/signup description: >- Page where a customer signs up for a managed tariff. When the customer chooses the program in an OEM app, Flatpeak opens this URL with `program_id`, `oem_id` and `signup_reference` as query parameters: see [sign-up from an OEM app](/fleet-api/guides/programs#sign-up-from-an-oem-app). A `listed` program with `managed` `true` needs it before its `status` can be `LIVE`. status: type: string enum: - DRAFT - LIVE - PAUSED description: >- Requested status. Requesting `LIVE` on a listed program submits it for OEM approval: it moves to `PENDING_APPROVAL` and goes live once approved. An unlisted program goes `LIVE` at once. example: LIVE Program: title: Program type: object description: >- A program you define: a VPP program, or a managed tariff when `managed` is `true`. Customers enroll in your app, or in their OEM's app once the program is `listed` and the OEM approves it. Enrolled devices arrive through Connect and fire `device.connect`. properties: id: type: string description: Flatpeak Program ID. example: vpr_5c8d1f2a7b3e4d6c9a0f1b2c object: type: string description: Object type, `vpp_program`. example: vpp_program enum: - vpp_program live_mode: type: boolean description: '`true` for live data, `false` for test data.' example: true display_name: type: string description: Program name shown to customers. example: Community Powershare description: type: string description: Short description shown to customers at enrollment. example: Earn from grid events while you keep your tariff. url: type: string nullable: true description: Public page with program details. example: https://pick.com/programs/community-powershare managed: type: boolean default: false example: false description: >- `true` for a managed tariff: you run the device under this program with [plans](/fleet-api/reference/plans/submit), and it replaces the customer's tariff. Plans are accepted only for devices enrolled in a managed program. Any number of programs can be managed. listed: type: boolean default: true example: true description: >- `true` to offer the program in OEM apps to eligible devices. Listing requires OEM approval, tracked by `status`. A program that is not listed goes `LIVE` without approval and is reachable only from your own app with `program_id` on the Connect session. currency_code: type: string example: USD description: >- Currency of every amount on the program, as an ISO 4217 code: `estimate.amount` and each `rate` in `terms.rewards`. Must match the market currency of the devices the program targets. Set on create and never changed. estimate: type: object description: >- What the customer is told to expect before they join. It is a projection and never binding. The copy follows `managed`: bill savings for a managed tariff, earnings otherwise. required: - amount - period properties: amount: type: number example: 612 description: >- Estimated amount for one `period`, in the program's `currency_code`, in large currency units: bill savings when `managed` is `true`, earnings otherwise. period: type: string enum: - YEAR - MONTH example: YEAR description: Period the estimate covers. dispatch_events_per_month: type: number minimum: 0 example: 15 description: Approximate number of VPP events per month the estimate assumes. terms: type: object description: >- What binds you and the customer once they have joined: what you pay, whether they may skip events, and how long leaving takes. The enrollment keeps a copy of the `terms` it joined with, so a change applies only to later enrollments. properties: rewards: type: array description: >- What the customer is paid. Each `basis` appears at most once. A `listed` program with `managed` `false` needs at least one reward before its `status` can be `LIVE`. A managed tariff may have none. example: - basis: FIXED rate: 15 period: QUARTER - basis: DELIVERED_KWH rate: 0.35 items: type: object required: - basis - rate properties: basis: type: string enum: - FIXED - EVENT - DELIVERED_KWH - COMMITTED_KWH example: DELIVERED_KWH description: >- What `rate` is paid for. | Value | `rate` is paid | | :--- | :--- | | `FIXED` | Once per `period`, by calendar period, pro-rated by the days the enrollment is `ACTIVE` | | `EVENT` | Per VPP 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 a VPP event, whatever the device then delivers. Nothing for a commitment the customer opted out of | rate: type: number example: 0.35 description: >- Amount paid per unit of `basis`, in the program's `currency_code`, in large currency units. period: type: string enum: - MONTH - QUARTER - YEAR example: QUARTER description: >- Period a `FIXED` reward is paid for. Required when `basis` is `FIXED`, and not used otherwise. opt_out_policy: type: string enum: - ALLOWED - ALLOWED_BEFORE_LOCK - NOT_ALLOWED example: ALLOWED description: >- Whether customers may skip individual VPP events. | Value | Meaning | | :--- | :--- | | `ALLOWED` | Default. Any scheduled or active VPP event. Skipped intervals are recorded as `OPTED_OUT`. | | `ALLOWED_BEFORE_LOCK` | Only until the allocation locks. | | `NOT_ALLOWED` | No per-event opt-out. Customers can still unenroll. | default: ALLOWED notice_days: type: integer example: 30 description: >- Maximum number of days leaving may take once the customer is enrolled. A request to leave that you have not approved ends after this many days. Shown to the customer before they join and when they leave. eligibility: type: object description: Which devices can join the program. properties: oem_ids: type: array items: type: string description: >- [OEM IDs](/fleet-api/reference/oems/list) the program is enabled for. Omit to enable it for every OEM available to your account. example: - oem_6a3a8dada72cd0a249ff9528 device_types: type: array items: type: string enum: - BATTERY_STORAGE - ELECTRIC_VEHICLE - EV_CHARGER - PV_SYSTEM - OTHER description: Device types the program accepts. example: - BATTERY_STORAGE zone_id: type: string nullable: true description: >- Restrict eligibility to a [network zone](/fleet-api/reference/zones/retrieve). min_storage_capacity_kwh: type: number nullable: true example: 5 description: >- Minimum usable storage capacity, in kWh, for a device to qualify. min_export_power_kw: type: number nullable: true example: 3 description: Minimum export power, in kW, a device must support to qualify. telemetry_requirements: type: object description: >- Telemetry the program requires from enrolled devices. A program that samples finer than an OEM's fleet can sustain is not offered to that OEM's devices. Omit the group to use Flatpeak's default intervals. required: - device_meter_interval_seconds properties: state_interval_seconds: type: integer minimum: 60 example: 300 description: >- Sampling interval for device state, in seconds, minimum 60. A sample is due when the interval has elapsed and a signal changed. While nothing changes the device sends a heartbeat, which Flatpeak sets at three times this interval and never below 300 seconds. Feed health (`state_data_delayed`) is judged against the heartbeat. device_meter_interval_seconds: type: integer minimum: 60 example: 900 description: >- Sampling interval for the device's own meter records, in seconds, minimum 60. Required, because every program settles on device meter records. Delivery cadence is separate. enrollment: type: object description: How a device gets in. properties: join_days: type: integer example: 10 description: >- Maximum number of days enrollment may take after the customer asks to join. Shown to the customer before they join. approval_required: type: boolean default: false example: false description: >- When `true`, each enrollment waits at `AWAITING_APPROVAL`, after the dispatch test, for your decision: approve it, or unenroll it to turn it down. When `false`, Flatpeak approves it. dispatch_test_required: type: boolean default: true example: true description: >- When `true`, the default, Flatpeak issues a `TEST` VPP event during enrollment, and the device must deliver it to pass. When `false`, the step is skipped. signup_url: type: string nullable: true example: https://phase.com/tariffs/flex/signup description: >- Page where a customer signs up for a managed tariff. When the customer chooses the program in an OEM app, Flatpeak opens this URL with `program_id`, `oem_id` and `signup_reference` as query parameters: see [sign-up from an OEM app](/fleet-api/guides/programs#sign-up-from-an-oem-app). A `listed` program with `managed` `true` needs it before its `status` can be `LIVE`. status: type: string enum: - DRAFT - PENDING_APPROVAL - LIVE - PAUSED - REJECTED description: >- Only `LIVE` programs are shown to customers. Approval applies to listed programs; an unlisted program goes `LIVE` on request. Changes fire `program.update`. | Value | Meaning | | :--- | :--- | | `DRAFT` | Private | | `PENDING_APPROVAL` | `LIVE` requested, under review by the OEMs in `eligibility` | | `LIVE` | Published | | `REJECTED` | An OEM declined; see `rejection_reason` | | `PAUSED` | No new enrollments | example: LIVE rejection_reason: type: string nullable: true readOnly: true description: Why the OEM rejected the program. Set when `status` is `REJECTED`. example: Estimated earnings are not supported by the reward terms. time_created: type: string format: date-time description: Time when the object was created, in UTC. example: '2026-08-12T09:30:00Z' account_id: type: string description: Flatpeak Account ID of the operator that owns the program. example: acc_649d465ede6a785d2fa5f905 required: - id - object - live_mode - display_name - managed - listed - currency_code - estimate - terms - eligibility - enrollment - status - time_created - account_id Error: type: object description: Standard error envelope returned by every non-2xx response. required: - object - type - code - message properties: object: type: string enum: - error default: error description: Object type. type: type: string description: High-level error category. example: invalid_request code: type: string description: Machine-readable error code, safe to branch on. example: access_denied message: type: string description: Human-readable description of the error. example: The requested resource could not be found. context: type: string description: Optional originating context, for example `api.price_get`. example: api.price_get live_mode: type: boolean description: Whether the error occurred against live or test data. time_created: type: string format: date-time description: Time the error was generated (RFC 3339). example: '2026-01-01T00:00:00Z' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Authenticate with the `bearer_token` obtained from the [authentication](/fleet-api/reference/authentication) endpoint. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.