Skip to main content

Partner campaign & affiliate verbs

Modules: programs:connect (campaigns) + programs:affiliate (codes) | Endpoint: Workspace MCP at https://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 optional referral_code, and optional forward_params (the link parameters it passes on to the landing page). There is no programme catalogue — program_id is 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 TBC until 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 as 0.
  • 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).

ParameterTypeRequiredDescription
campaign_idstringnoOpen one campaign.
statusstringnoOnly campaigns in this status: draft, active, paused, completed.
include_archivedbooleannoInclude archived campaigns. Default false.
limit / offsetintegernoPaging (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 linkMeaning
?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=1Preview 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.

ParameterTypeRequiredDescription
campaign_idstringnoOne campaign; omit for all.
since / untilstringnoISO dates for the window.

create_campaign​

Create a campaign in draft and get its link.

ParameterTypeRequiredDescription
namestringyesCampaign name, e.g. "Paua cards: referral".
landing_urlstringnoWhere the link sends people: an https ev.energy address.
referral_codestringnoThe code the link credits, 2–16 letters/digits. Omit for a link that credits nobody, such as card activation.
forward_paramsarraynoLink parameters to pass to landing_url, e.g. ["printed_id"]. A link to the card activation page always passes printed_id.
program_idstringnoFree-text programme label.
webhook_urlstringnoYour 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.

ParameterTypeRequiredDescription
campaign_idstringyesCampaign to change.
name, landing_url, referral_codestringnoNew values; '' clears landing_url or referral_code.
forward_paramsarraynoReplaces the forwarded parameters; [] forwards none.
statusstringnoactive, paused or completed. completed is final and needs confirmed: true.
archivedbooleannotrue hides the campaign (history kept); false restores it.
confirmedbooleannoSet 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.

ParameterTypeRequiredDescription
campaign_idstringyesCampaign to launch.
base_urlstringnoOrigin 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.

ParameterTypeRequiredDescription
user_emailstringnoUser's email (a hint).
program_idstringnoSmart-charging programme ID.
messagestringnoFree-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).

ParameterTypeRequiredDescription
task_idstringyesTask 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.

ParameterTypeRequiredDescription
redemptionsbooleannotrue for redemption rows instead of codes.
codestringnoWith redemptions: one code, e.g. "SUNRUNQ3".
sincestringnoWith 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.

ParameterTypeRequiredDescription
codestringyesThe public code drivers type, e.g. "SUNRUNQ4".
labelstringnoInternal name for your reference; not shown to drivers.
campaign_refstringnoOptional 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.

ParameterTypeRequiredDescription
codestringyesWhich code to change.
labelstringnoNew internal name.
campaign_refstringnoNew reporting tag.
statusstringnoinactive disables the code — it stops attributing new sign-ups; its redemption history is kept.

Returns: the updated code.


The full set at a glance​

VerbModuleWrite?Notes
list_campaignsconnectreadyour campaigns, settings, links; one campaign's contacts
view_campaign_performanceconnectwritefunnel, clicks by channel and forwarded parameter; closes a finished campaign
create_campaignconnectwritename, landing_url, referral_code, forward_params; returns the link
update_campaignconnectwritename, landing_url, referral_code, forward_params, status, archived; completed needs confirmation
create_contactsconnectwritebulk emails; duplicates and invalid skipped
launch_campaignconnectwriteenrolment tasks and invite links
enroll_userconnectwritesingle enrolment task
get_enrollment_task_statusconnectreadpoll an enrolment task
list_codesaffiliatereadcodes and their performance, or redemption rows
create_codeaffiliatewriteadmin/owner; org-bound
update_codeaffiliatewriterename/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.