Eve gets you enrolled, then keeps you earning
Module:
None(driver-facing, no workspace module required) | Role: EV driver | Licence: Free+ | Auth: ev.energy account login (Clerk OAuth)
Audience: drivers and partners who want to know what Eve Connect does across a driver's whole relationship with ev.energy. The overview is connect; the structural map is connect/ia; the verb reference is connect/verbs.
Eve has two jobs, in order: get a driver enrolled, then keep them earning. Those are the two lifecycles, and every driver question belongs to one of them.
- Enrollment answers "what can I get, and how do I get it?"
- In-life answers "how am I doing, and how do I get more?"
The boundary is whether setup is complete. Eve reads your account on every turn, and my_account returns a five-item setup checklist plus the next_step. While any step is outstanding she is in enrollment mode. Once all five are ticked she stops running a wizard and becomes reactive.
What changes between the phases is what Eve says. What never changes is where the facts come from: your ev.energy account, over the public v2 API, cited below for every claim on this page.
Enrollment answers "what can I get, and how do I get it?"
The journey from cold visitor to enrolled-and-earning:
Discover → Sign in → Onboard a device → Enrol → Earn → Earn more
(ask Eve) (OAuth) (connect_device) (join) (live) (loop)
- Discover. Ask "what could I earn near me?" before connecting anything. Eve searches programmes by location:
GET /v2/programs?country_code=<ISO-2>&postal_code=<code>. If no location is on file she asks for a postcode and searches near it without writing it to your profile. Unfiltered, that endpoint returns the global catalogue, so the location filter is what keeps a GB driver from being shown Connecticut programmes. - Sign in. One OAuth round-trip with your ev.energy account. Signing in and creating an account are the same step; there is no separate "register".
- Onboard a device.
connect_deviceonboards a car. Eve matches your free-text description against the vehicle catalogue (GET /v2/vehicle_makes,GET /v2/vehicle_models,GET /v2/vehicle_trims) and hands back an OEM authorisation link. Authorisation runs on ev.energy'svehicle-authorizationendpoints, the same flow the ev.energy app uses, and the finished car then appears onGET /v2/vehicles. Chargers, home batteries and solar are paired in the ev.energy app, and Eve says so rather than offering a link she cannot produce. The charger catalogue (GET /v2/evse_makes,GET /v2/evse_models) is a read-only compatibility lookup that answers "will my charger work?"; it onboards nothing. - Enrol.
join_program→POST /v2/programs/{program_id}/join. Programmes with no in-app tier (community and innovation trials) return the sponsor's ownexternal_urlinstead, and Eve hands you there. - Earn. Savings and earnings start accruing; you are now in-life.
- Earn more. Connect more devices, switch to a better-paying programme, refer friends.
Having a session is not the same as being a connected driver. Steps 3 and 4 are the real activation, not step 2.
Five setup steps run in a fixed order
One friendly ask per turn, each written to your account and then re-read so Eve never claims a step landed that did not.
| # | Step | What it sets | Read / written as |
|---|---|---|---|
| 1 | Account | Your ev.energy login | Ticked from your signed-in session; profile at GET /v2/users/{user_id} |
| 2 | Device | Car, charger, battery or solar | GET /v2/vehicles, GET /v2/evses, GET /v2/solar_arrays |
| 3 | Location | The postcode Eve schedules and searches around | PATCH /v2/users/{user_id} with default_location (address_1, postal_code, country_code) |
| 4 | Tariff | The rate plan your supplier has you on | Catalogue GET /v2/tariffs?available_for_user_id=<user_id>; set via default_location.tariff on the same PATCH |
| 5 | Earnings | The programme that pays you to flex | GET /v2/programs, then POST /v2/programs/{program_id}/join |
Tariff and Earnings are separate steps because a tariff is not a programme. A tariff is the named rate plan your supplier puts you on, such as Octopus Go, Intelligent Octopus Go or OVO Charge Anytime, and it decides what you pay per unit. A programme is an earnings or demand-response scheme you join, such as Charge & Earn or ev.energy UK, and it decides how you are paid for being flexible. Charge & Earn is a programme you join; Octopus Go is a tariff you are on. You have one of each, independently. They live on different records and different endpoints: a tariff on your account's default_location, a programme on your membership record. See You keep your tariff when you join a programme.
One programme at a time. A driver holds at most one programme membership. POST /v2/programs/{program_id}/join leaves your current programme before joining the new one, so "earn more" between programmes is a switch, not a stack. Eve names the programme you would leave, and asks, before making the call.
Eve shortlists programmes and says which one she would pick
Every programme fact comes from GET /v2/programs/{program_id}: name, description, benefits, eligibility_criteria, sponsor_name, country, external_url, sign_up_url, faqs_url, support_email, payment_frequency, payment_day_of_month, payment_weekday, logo. Rich text is reduced to clean readable text first, so it reads and speaks the same on every surface.
Asked what you could join, Eve reads GET /v2/programs?country_code&postal_code for where you are and puts one to three programmes in front of you with a recommendation and the reason for it, rather than a catalogue to sort. For each she names what the programme does, what it pays and what it asks of you in return, quoting the record's own benefits and description. She never invents a figure.
Whether you can join is read from the programme, never assumed
Conditions live in eligibility_criteria on the programme's own record, for example a smart-meter requirement or a smart tariff the programme excludes, and Eve quotes them as written rather than judging you against them. Whether your car qualifies is a separate check at GET /v2/programs/{program_id}/vehicle_compatibility. Where the record is silent, Eve says she cannot confirm it and offers the programme's support_email or faqs_url, which is the honest answer and a better one than a guess.
Every later change is one ask, never the wizard again
Setup runs once. Adding a second car, switching tariff, changing where you are paid or moving to another programme is a single ask and a single write after that, with no checklist to walk again. The join step is the one that needs care: a driver who already holds a membership and arrives back at it is switching, so Eve names the programme they would leave and confirms before calling POST /v2/programs/{program_id}/join.
In-life answers "how am I doing, and how do I get more?"
No wizard and no checklist. Eve refreshes your state with my_account at the start of every turn and answers in a line or two. Every in-life story, and what answers it:
| You ask | Verb | Read from |
|---|---|---|
| "Is it plugged in? What's the battery at? Is it charging? Will it be ready?" | my_account | The live block on each car from GET /v2/vehicles plus its latest charging status: plug state, battery percentage, charging now, and the ready-by time when the car reports one |
| "What did I save last month? What did I spend? How much have I used?" | my_transactions | GET /v2/charging_sub_sessions for home charging (energy and savings on each session) plus public charging on ev.energy cards. saved, spent and energy.kwh for the window, with the items behind them |
| "How much for public charging?" | my_transactions | spent and the items whose where is a charging network: public charging paid through the ev.energy account. Home items say "where": "Home" |
| "How much have I earned overall?" | my_transactions | earned = per-session charging incentives (incentive_earned on GET /v2/charging_sub_sessions) plus rebates paid to the account (GET /v2/user_rebates), each an item of kind reward. Kept apart from saved, never quoted as each other |
| "What did my battery or solar make me?" | The app | Not on my_transactions: v2 has their device state (GET /v2/home_batteries, GET /v2/solar_arrays) but no settled payout ledger yet, so Eve hands you to the app rather than guessing a total. The named core ask below |
| "What programme am I in, and how do I earn on it?" | my_account | my_account().data.program (singular, or null: you are in at most one): your membership from GET /user-program-details/user/, hydrated with benefits, description and eligibility_criteria from GET /v2/programs/{program_id}, so an enrolled driver gets the same detail a prospect does |
| "How do I actually get my rewards?" | my_account | The same record, quoted as written. Charge & Earn rewards build up as a balance you redeem in the ev.energy app when you choose, so no payday is promised. A payment_frequency, payment_day_of_month or payment_weekday is quoted only when the record carries one |
| "What counts? Am I eligible? Why am I still pending?" | my_account | eligibility_criteria on the programme record, plus the verification_status and field schema on your membership read, which is what tells Eve exactly which detail is outstanding and lets you supply it in the conversation |
| "How am I paid, and where do my rewards land?" | my_account, then update_account | my_account().data.payout_method (method, configured) from GET /v2/users/{user_id}/payout_method; you set it (PayPal, Venmo or bill credit) in the ev.energy app, never through Eve or a connected AI, because it decides where your money goes |
| "What's my rate? Who's my supplier? Switch me." | my_account, discover, update_account | my_account().data.tariff carries name, currency, daily_prices, type and valid_from / valid_until from GET /v2/tariffs/{tariff_id}; alternatives from discover(scope="tariffs"); the change is update_account(tariff_id=…), confirmed first |
| "What have I got connected? Cap the charge. Take that one off." | my_account, update_device, remove_device | my_account().data.vehicles and my_account().data.chargers (your own devices live on my_account, not discover); maximum_charge_limit_percentage, 50 to 100, via PATCH /v2/vehicles/{vehicle_id}; removal via DELETE /v2/vehicles/{vehicle_id} or DELETE /v2/evses/{evse_id}, confirmed first |
| "Will my car work? Will my charger work?" | discover | discover(scope="vehicle_makes") returns the makes supported for you (GET /v2/vehicle_makes?available_for_user_id=me, fully paginated), so it names cars ev.energy actually supports rather than a partial list; then vehicle_models / vehicle_trims for detail. discover(scope="charger_makes") returns the charger catalogue (GET /v2/evse_makes) read-only. One honest caveat on chargers: the catalogue is not exhaustive, so a charger not listed can still be supported (myenergi/Zappi is, via its own integration, and many chargers work through the generic OCPP path); the real test is onboarding, and chargers, batteries and solar are paired in the ev.energy app |
| "How do I earn more?" | connect_device, join_program, update_account, refer_friend | In rough order of size: connect another asset (a battery, solar or a second car moves the number most), move to a better-paying programme, set a payout method in the app so earnings have somewhere to land, refer a friend |
| "Move me to that other programme." | join_program | POST /v2/programs/{program_id}/join. One programme at a time, so the join leaves your current one; Eve names it and asks first |
| "I want to leave my programme." | leave_program | PUT /user-program-details/user/leave/, confirmation-gated. Earnings from that programme stop. Your smart-charging savings belong to your account, not the programme, so they carry on for as long as you keep smart charging |
| "What am I subscribed to?" | my_account | my_account().data.subscriptions from GET /v2/subscriptions/: account offerings such as ev.energy Solar Lifetime. Not programme membership, which is the row three up |
| "Are there rebates I could get?" | The app | US utility bill-credit rebates are discovered and claimed in the ev.energy app, gated to the schemes your utility runs. There is no discover scope for them: a rebate catalogue returns nothing for a GB driver. For "what could I earn?", discover(scope="programs") shows the flexibility programmes near your saved location |
| "What's my referral link?" | refer_friend | The referral code on your ev.energy account, returned as a code, a share link and a QR. It sends nothing, so Eve asks you to pass the link on yourself, and how many friends have joined is not readable here yet |
| "Boost it now. Pause the charge. Lock the charger." | The app | There is no device-control write on this surface. Eve hands you to the ev.energy app rather than claiming to have acted |
| "How does this save me money? What is a time-of-use tariff? Are you safe with my data?" | No tool call | Eve's own answer, cited to the public ev.energy site. Nothing here is about your account, so there is nothing to read |
Savings and earnings are two different things, and Eve keeps them apart even though both now come back on one my_transactions statement. Savings are your bill going down from smart charging: an account fact, computed from your real charging history, never estimated at you. Earnings are cash a programme pays you for being flexible: per-session charging incentives plus rebates paid to the account. They sit side by side as saved and earned, and are never quoted as each other. Your subscriptions are a third axis again, and joining a programme never creates one. See Savings and earnings.
Twelve stories cover what drivers actually ask for
The canonical set, one line each, tagged by lifecycle.
| # | Story | Lifecycle |
|---|---|---|
| S1 | I have just bought an EV; sign me in and walk me through car, postcode, tariff and an earnings programme without five other tabs. | Enrollment |
| S2 | Tell me what I saved this month and what I earned, as two separate numbers. | In-life |
| S3 | I already have my EV connected; let me add a battery or a charger without restarting the wizard. | In-life |
| S4 | Answer "is my car plugged in?" or "what tariff am I on?" from my real account, in one line. | In-life |
| S5 | Tell me what I can join near my postcode, so I capture programmes I would otherwise miss. | Both |
| S6 | Let me point my own AI client at Connect, authorise once, and use these verbs from inside it. | Both |
| S7 | If Eve cannot do something yet, hand me cleanly to the ev.energy app rather than dead-ending. | In-life |
| S8 | Show me exactly what an AI client can see before I authorise it, and never ask for my password. | Enrollment |
| S9 | Get my country, currency and tariff names right the moment I sign in, not after I configure anything. | Both |
| S10 | Show me which AI clients I have connected, and let me revoke one cleanly. | In-life |
| S11 | Let me activate the charging card in my hand, make a card my default, pause it, report it lost, and add or remove a payment card. | In-life |
| S12 | Tell me what happened on my account, in words written for me, wherever I talk to Eve, and keep what I've seen seen everywhere. | In-life |
Each of the 15 verbs does a different job in each lifecycle
| Verb | Enrollment | In-life |
|---|---|---|
my_account | Which of the five steps are done, and the next one to do (setup, next_step). S1. | Live state in one read: devices and their live charge state, location, tariff detail, payout method, and the enrolled programme with its own rules. S4, S9. |
discover | Browse the catalogues: car makes, models and trims, chargers for compatibility, programmes near you, tariffs, suppliers. S1, S5. | My devices, my programme, my subscriptions, rebates, the charger catalogue when new kit arrives; re-check what is newly available near me. S3, S5. |
connect_device | Step 2, the first car. Chargers, batteries and solar are paired in the ev.energy app. S1. | Every car after the first, one-shot, no wizard reset. S3, and the biggest earn-more lever. |
join_program | Step 5, the first earnings programme. S1, S5. | Switch programme; the join leaves the current one first, and Eve warns you by name. S5. |
update_account | Steps 3 and 4, home location then tariff. S1. | Moved house, switched supplier or tariff, changed where earnings are paid. S4, S7. |
update_device | n/a: not one of the five setup steps, and there is no device to configure until step 2 completes. | Set a vehicle's charge limit (maximum_charge_limit_percentage, 50 to 100). |
my_transactions | n/a: nothing to report before your first smart charge; Eve quotes real sessions, never an estimate dressed as history. | The driver's account over a window: earned, spent, saved, energy and pending, with the items behind them (home sessions and public charging on ev.energy cards). Battery and solar earnings are not on it yet. S2. |
remove_device | Undo a wrong match, such as the wrong trim or a car you no longer own, before it shapes your schedule. | Sold the car, replaced the charger. Re-pairing from scratch is needed afterwards, so Eve confirms first. |
leave_program | n/a: you hold no membership before the first join, and switching between programmes is handled by join_program. | Leave and stop earning; Eve says what stops and what carries on before doing it. |
refer_friend | Share your code as soon as you are signed in; it exists on your account from the start. | Referrals as a standing earn-more lever; both sides are credited when a friend signs up. |
my_notifications | n/a: nothing has happened on the account to tell you about yet. | What happened on your account (a public charge, a declined card, a refund), newest first; showing them marks them read on every surface. S12. |
Every fact Eve states has a public home
One rule holds this together, and it is the same in both lifecycles:
Every fact Eve states about a programme, a device, a tariff or a number has a public home: the ev.energy API or a public web page. Eve never states a fact she cannot point you to.
| Fact | Source |
|---|---|
| Programmes available near me | GET /v2/programs?country_code&postal_code |
| Programme detail, rules, eligibility, payment fields | GET /v2/programs/{program_id} |
| Will my car qualify | GET /v2/programs/{program_id}/vehicle_compatibility |
| Join a programme | POST /v2/programs/{program_id}/join |
| The programme I am in, and my verification state | GET /user-program-details/user/, one active membership or none |
| Leave my programme | PUT /user-program-details/user/leave/ |
| My subscriptions (not programme membership) | GET /v2/subscriptions/ |
| Tariffs I can be on | GET /v2/tariffs?available_for_user_id · detail at GET /v2/tariffs/{tariff_id} |
| Suppliers | GET /v2/suppliers |
| My account, address and tariff | GET /v2/users/{user_id} · PATCH /v2/users/{user_id} (default_location) |
| Where my rewards land | GET / PATCH /v2/users/{user_id}/payout_method |
| My notifications, and what I have seen | the eMSP's GET /notifications and POST /notifications:seen, as the driver |
| My devices | GET /v2/vehicles · GET /v2/evses · GET /v2/solar_arrays |
| Supported car makes for you | GET /v2/vehicle_makes?available_for_user_id=me (paginated); models/trims via /v2/vehicle_models · /v2/vehicle_trims |
| Charger catalogue (compatibility, not exhaustive) | GET /v2/evse_makes · GET /v2/evse_models |
| One device in detail, and its live state | GET /v2/vehicles/{vehicle_id} · GET /v2/vehicles/{vehicle_id}/status_logs · GET /v2/evses/{evse_id} |
| Change a device setting | PATCH /v2/vehicles/{vehicle_id} |
| Remove a device | DELETE /v2/vehicles/{vehicle_id} · DELETE /v2/evses/{evse_id} |
| Charging history: savings, usage, cost, per-session incentives | GET /v2/charging_sub_sessions (carries savings_cost, cost, energy, incentive_earned, vehicle, evse, mode, location) · GET /v2/charging_sub_sessions/{session_id}/energy_usage |
| Account-level rebate payouts (the second earnings stream) | GET /v2/user_rebates |
| Battery / solar earnings | No settled payout ledger on v2 yet, so they are not on my_transactions. Device state only, at GET /v2/home_batteries · GET /v2/solar_arrays. The named core ask |
| Rewards and rebates I could qualify for | GET /v2/rebate_types |
| My referral code | The referral code on your ev.energy account profile. v2 exposes no referral endpoint, and Eve never mints a code of her own |
| What a programme has paid me so far | my_transactions → earned: per-session charging incentives plus rebates paid to the account. Battery and solar earnings alone have no ledger yet |
Two of these deliberately sit outside the /v2 catalogue, because that is where the data honestly lives: programme membership (/user-program-details/user/) and the OEM authorisation hand-off used by connect_device. Everything else on this page is a public v2 endpoint. If Eve cannot confirm something from one of these, she says so rather than guessing, which is why what she tells you matches what you would find in the ev.energy app.