Partner campaign & affiliate verbs
Modules:
programs:connect(campaigns) +programs:affiliate(codes) | Endpoint: Workspace MCP athttps://eve.ev.energy/mcp| Auth: MCP OAuth | Scope: every verb is workspace-scoped — the workspace comes from the authenticated connection, never a parameter.
The partner surface lets an organisation recruit EV drivers with tracked campaign links and referral/promo codes, and measure the result. It is split across two modules that a workspace enables independently:
programs:connect— campaigns: create and change them, get their tracked links, add and invite contacts, and read how they are doing.programs:affiliate— codes: mint and manage the organisation's referral/promo codes and read their redemptions.
Every verb here is also available on the partner web pages (Affiliate, Campaigns, Campaign detail, Codes) when the modules are enabled — the web and the MCP tools read the same data, so they can never disagree. To wire an AI client to this surface see connecting a client.
The pipeline & what the figures mean
The partner funnel is four figures, in order:
Campaigns → Clicks → Redemptions → Qualified
- Campaign — the unit of work. A campaign is a free-text name plus an optional
landing_url(an ev.energy page a driver lands on) an optionalreferral_code, and optionalforward_params(the link parameters it passes on to the landing page). There is no programme catalogue —program_idis a free-text label only. - Clicks — ours, counted in real time. Every follow of a campaign's tracked
/connect/j/{short_code}share link is a click, attributed per campaign (and per contact when the link carries a contact tag). - Redemptions — core's. A driver who signs up using one of the organisation's codes is a redemption. This is core's per-code
redeemed_count. - Qualified — the subset of redemptions that completed a qualifying charge — core's per-code
qualified_count. Qualified is always at or below redemptions.
Three honesty rules the whole surface follows:
- Redemptions and qualified read
TBCuntil the workspace is linked to an ev.energy organisation (and its codes can be read). Clicks are workspace-local, so they are always real. A figure that cannot be read is shown as TBC, never as0. - Conversions are per-code, aggregate and anonymised — never per-driver. There is no per-referee identity on this surface.
- No monetary amounts are shown. Core does not report money yet, so any amount reads TBC. No amount is ever computed or returned by these verbs.
programs:connect — campaign verbs
Two reads and four writes. list_campaigns holds what you have (settings, links, contacts); view_campaign_performance holds how it is doing (the numbers).
list_campaigns
Without campaign_id: your campaigns, newest first, each with its settings and link, plus your workspace's own referral link. With campaign_id: that campaign's settings, link and a page of contacts (each with clicks and invite state).
| Parameter | Type | Required | Description |
|---|---|---|---|
campaign_id | string | no | Open one campaign. |
status | string | no | Only campaigns in this status: draft, active, paused, completed. |
include_archived | boolean | no | Include archived campaigns. Default false. |
limit / offset | integer | no | Paging (1–100 campaigns, 1–200 contacts, default 50). Page while has_more is true, or contacts_has_more when a campaign_id is given. |
Each link carries share_link, an example with the forwarded parameters filled in, credits (the referral code, or null when it credits nobody), forwards (the parameters it passes on), and you_can_add:
| Add to a link | Meaning |
|---|---|
?c=<contact_id> | A per-contact link; the click counts against that contact. |
?utm_source=<channel> | The channel, e.g. qr or linkedin; src is a short alias. |
?test=1 | Preview the destination without counting a click. |
?<your parameter>=… | Recorded on every click; passed to the landing page only if the campaign lists it in forward_params. |
view_campaign_performance
How your campaigns are doing. Without campaign_id: totals and a daily clicks-vs-redemptions series over a window (default the last 30 days). With campaign_id: its all-time stats and referral_funnel, plus clicks_in_window, the clicks in the window by channel and by each parameter in the campaign's forward_params (for example, scans per printed_id). Only clicks_in_window is windowed. A figure that cannot be read is null, never 0. An active campaign closes itself once every contact has finished.
| Parameter | Type | Required | Description |
|---|---|---|---|
campaign_id | string | no | One campaign; omit for all. |
since / until | string | no | ISO dates for the window. |
create_campaign
Create a campaign in draft and get its link.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | Campaign name, e.g. "Paua cards: referral". |
landing_url | string | no | Where the link sends people: an https ev.energy address. |
referral_code | string | no | The code the link credits, 2–16 letters/digits. Omit for a link that credits nobody, such as card activation. |
forward_params | array | no | Link parameters to pass to landing_url, e.g. ["printed_id"]. A link to the card activation page always passes printed_id. |
program_id | string | no | Free-text programme label. |
webhook_url | string | no | Your server's https webhook for invite task updates. Not a driver redirect. |
promo_code, c, utm_source, src and test belong to the link itself, so forward_params refuses them with an error that names the clash. So are keys a landing page may read as a referral code (ref, code, coupon, promo, promocode, referral, referral_code, referred_by): forwarding one would let anyone with the link credit their own code.
update_campaign
Change a campaign. Only the fields you pass change, and links already shared follow the new settings.
| Parameter | Type | Required | Description |
|---|---|---|---|
campaign_id | string | yes | Campaign to change. |
name, landing_url, referral_code | string | no | New values; '' clears landing_url or referral_code. |
forward_params | array | no | Replaces the forwarded parameters; [] forwards none. |
status | string | no | active, paused or completed. completed is final and needs confirmed: true. |
archived | boolean | no | true hides the campaign (history kept); false restores it. |
confirmed | boolean | no | Set only after the user agrees to close the campaign. |
create_contacts
Add driver contacts so launch_campaign can invite them. Each needs an email; name and phone are optional. Duplicates and invalid emails are skipped and counted.
launch_campaign
Send a campaign's invites: an enrolment task and invite link for every contact not yet launched, and the campaign moves to active. Safe to call again after adding contacts.
| Parameter | Type | Required | Description |
|---|---|---|---|
campaign_id | string | yes | Campaign to launch. |
base_url | string | no | Origin for invite links, e.g. https://eve.ev.energy. |
enroll_user
Create a single A2A enrolment task to onboard one user into smart charging (EV, charger, home battery, or solar). Returns an auth URL to share; poll get_enrollment_task_status until it reaches a terminal state.
The task completes when the invited user accepts the invite on Eve Connect (the invite only works for the email it was issued to). completed means invite accepted, not enrolled in smart charging: what the user does on Connect afterwards is theirs, and nothing about their account is reported back. An invite that expires unaccepted moves the task to failed.
| Parameter | Type | Required | Description |
|---|---|---|---|
user_email | string | no | User's email (a hint). |
program_id | string | no | Smart-charging programme ID. |
message | string | no | Free-text enrolment request. |
Returns: task_id and the auth URL.
get_enrollment_task_status
Poll the status of a task created by enroll_user (or launch_campaign).
| Parameter | Type | Required | Description |
|---|---|---|---|
task_id | string | yes | Task ID returned by enroll_user. |
Returns: the task state (input_required, completed, failed or canceled) and invite_accepted (true once the user has accepted the invite).
programs:affiliate — code verbs
Reads are open to any workspace member; writes (create_code, update_code) are admin/owner only. All three require the workspace to be linked to an ev.energy organisation — without the binding they return a clear "not linked" message rather than an empty account. No verb ever returns a monetary amount.
list_codes
Every code the organisation owns, active and disabled, each with redemptions (redeemed_count), how many qualified (qualified_count), its share_link and qr_url. With redemptions: true it returns individual redemptions instead: one row per redemption, not per driver, anonymised. No amounts.
| Parameter | Type | Required | Description |
|---|---|---|---|
redemptions | boolean | no | true for redemption rows instead of codes. |
code | string | no | With redemptions: one code, e.g. "SUNRUNQ3". |
since | string | no | With redemptions: on or after this date (YYYY-MM-DD). |
create_code
Mint a new code owned by the organisation. Codes are 2–16 characters, letters and digits only (no hyphens); the shape is checked before anything is sent. Admin/owner only.
| Parameter | Type | Required | Description |
|---|---|---|---|
code | string | yes | The public code drivers type, e.g. "SUNRUNQ4". |
label | string | no | Internal name for your reference; not shown to drivers. |
campaign_ref | string | no | Optional tag for grouping codes in reporting. |
Returns: the created code.
update_code
Rename, retag, or disable a code. The code string is immutable and a code is never deleted. Admin/owner only.
| Parameter | Type | Required | Description |
|---|---|---|---|
code | string | yes | Which code to change. |
label | string | no | New internal name. |
campaign_ref | string | no | New reporting tag. |
status | string | no | inactive disables the code — it stops attributing new sign-ups; its redemption history is kept. |
Returns: the updated code.
The full set at a glance
| Verb | Module | Write? | Notes |
|---|---|---|---|
list_campaigns | connect | read | your campaigns, settings, links; one campaign's contacts |
view_campaign_performance | connect | write | funnel, clicks by channel and forwarded parameter; closes a finished campaign |
create_campaign | connect | write | name, landing_url, referral_code, forward_params; returns the link |
update_campaign | connect | write | name, landing_url, referral_code, forward_params, status, archived; completed needs confirmation |
create_contacts | connect | write | bulk emails; duplicates and invalid skipped |
launch_campaign | connect | write | enrolment tasks and invite links |
enroll_user | connect | write | single enrolment task |
get_enrollment_task_status | connect | read | poll an enrolment task |
list_codes | affiliate | read | codes and their performance, or redemption rows |
create_code | affiliate | write | admin/owner; org-bound |
update_code | affiliate | write | rename/retag/disable; never deletes |
Everything above is also on the partner web pages (Affiliate, Campaigns, Campaign detail, Codes) when the modules are enabled — the MCP verbs and the web read the same payloads.