Skip to main content

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)
  1. 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.
  2. 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".
  3. Onboard a device. connect_device onboards 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's vehicle-authorization endpoints, the same flow the ev.energy app uses, and the finished car then appears on GET /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.
  4. Enrol. join_program → POST /v2/programs/{program_id}/join. Programmes with no in-app tier (community and innovation trials) return the sponsor's own external_url instead, and Eve hands you there.
  5. Earn. Savings and earnings start accruing; you are now in-life.
  6. 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.

#StepWhat it setsRead / written as
1AccountYour ev.energy loginTicked from your signed-in session; profile at GET /v2/users/{user_id}
2DeviceCar, charger, battery or solarGET /v2/vehicles, GET /v2/evses, GET /v2/solar_arrays
3LocationThe postcode Eve schedules and searches aroundPATCH /v2/users/{user_id} with default_location (address_1, postal_code, country_code)
4TariffThe rate plan your supplier has you onCatalogue GET /v2/tariffs?available_for_user_id=<user_id>; set via default_location.tariff on the same PATCH
5EarningsThe programme that pays you to flexGET /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 askVerbRead from
"Is it plugged in? What's the battery at? Is it charging? Will it be ready?"my_accountThe 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_transactionsGET /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_transactionsspent 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_transactionsearned = 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 appNot 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_accountmy_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_accountThe 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_accounteligibility_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_accountmy_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_accountmy_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_devicemy_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?"discoverdiscover(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_friendIn 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_programPOST /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_programPUT /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_accountmy_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 appUS 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_friendThe 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 appThere 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 callEve'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.

#StoryLifecycle
S1I have just bought an EV; sign me in and walk me through car, postcode, tariff and an earnings programme without five other tabs.Enrollment
S2Tell me what I saved this month and what I earned, as two separate numbers.In-life
S3I already have my EV connected; let me add a battery or a charger without restarting the wizard.In-life
S4Answer "is my car plugged in?" or "what tariff am I on?" from my real account, in one line.In-life
S5Tell me what I can join near my postcode, so I capture programmes I would otherwise miss.Both
S6Let me point my own AI client at Connect, authorise once, and use these verbs from inside it.Both
S7If Eve cannot do something yet, hand me cleanly to the ev.energy app rather than dead-ending.In-life
S8Show me exactly what an AI client can see before I authorise it, and never ask for my password.Enrollment
S9Get my country, currency and tariff names right the moment I sign in, not after I configure anything.Both
S10Show me which AI clients I have connected, and let me revoke one cleanly.In-life
S11Let 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
S12Tell 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​

VerbEnrollmentIn-life
my_accountWhich 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.
discoverBrowse 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_deviceStep 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_programStep 5, the first earnings programme. S1, S5.Switch programme; the join leaves the current one first, and Eve warns you by name. S5.
update_accountSteps 3 and 4, home location then tariff. S1.Moved house, switched supplier or tariff, changed where earnings are paid. S4, S7.
update_devicen/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_transactionsn/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_deviceUndo 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_programn/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_friendShare 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_notificationsn/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.

FactSource
Programmes available near meGET /v2/programs?country_code&postal_code
Programme detail, rules, eligibility, payment fieldsGET /v2/programs/{program_id}
Will my car qualifyGET /v2/programs/{program_id}/vehicle_compatibility
Join a programmePOST /v2/programs/{program_id}/join
The programme I am in, and my verification stateGET /user-program-details/user/, one active membership or none
Leave my programmePUT /user-program-details/user/leave/
My subscriptions (not programme membership)GET /v2/subscriptions/
Tariffs I can be onGET /v2/tariffs?available_for_user_id · detail at GET /v2/tariffs/{tariff_id}
SuppliersGET /v2/suppliers
My account, address and tariffGET /v2/users/{user_id} · PATCH /v2/users/{user_id} (default_location)
Where my rewards landGET / PATCH /v2/users/{user_id}/payout_method
My notifications, and what I have seenthe eMSP's GET /notifications and POST /notifications:seen, as the driver
My devicesGET /v2/vehicles · GET /v2/evses · GET /v2/solar_arrays
Supported car makes for youGET /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 stateGET /v2/vehicles/{vehicle_id} · GET /v2/vehicles/{vehicle_id}/status_logs · GET /v2/evses/{evse_id}
Change a device settingPATCH /v2/vehicles/{vehicle_id}
Remove a deviceDELETE /v2/vehicles/{vehicle_id} · DELETE /v2/evses/{evse_id}
Charging history: savings, usage, cost, per-session incentivesGET /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 earningsNo 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 forGET /v2/rebate_types
My referral codeThe 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 farmy_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.