Skip to content
/
Update a referral code

Update a referral code

Request

Update a referral code's label, campaign_ref or status.

The code string is immutable once issued — it is printed on physical media and embedded in live links — and an attempt to change it is rejected rather than silently ignored. There is deliberately no DELETE: a code is the attribution key for every redemption made against it and any commission owed, so status: INACTIVE stops new redemptions and preserves all history.

Security
oauth2(Required scopes: referral:manage)
Path
referral_code_idstringprom[A-Z\d]{26}required

The ID of the referral code.

Example:prom01JZQ8V5T7MKXR9NBCDEFGHJ4A
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value:2
Accept-Languagestring

Indicates the natural language and locale that the client prefers.

Bodyapplication/json
labelstring
Example:"Summer forecourt"
campaign_refstring
Example:"summer-forecourt"
statusstring
Enum:"ACTIVE""INACTIVE"
Example:"INACTIVE"
curl -i -X PATCH \
  https://developers.ev.energy/_mock/ev.energy-api-v2/referral_codes/prom01JZQ8V5T7MKXR9NBCDEFGHJ4A \
  -H 'Accept-Language: string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'EvEnergy-Version: 2' \
  -d '{
    "label": "Summer forecourt",
    "campaign_ref": "summer-forecourt",
    "status": "INACTIVE"
  }'

Responses

The code was updated.

Headers
EvEnergy-Versionnumber

Indicates the version of the API that generated this response. If EvEnergy-Version was not specified in the request, this will be your OAuth application's default version.

Value:2
Bodyapplication/json
idstringprom[A-Z\d]{26}read-onlyrequired

Unique identifier for the given referral code.

Example:"prom01JZQ8V5T7MKXR9NBCDEFGHJ4A"
urlstring, (uri)read-onlyrequired
Example:"https://api.ev.energy/v2/referral_codes/prom01JZQ8V5T7MKXR9NBCDEFGHJ4A"
codestring^[A-Za-z0-9]{2,16}$required

The public string a driver types. Immutable once issued.

Example:"SPRING24"
labelstring

Internal name for the owning organisation's UI. Never shown to drivers.

Example:"Forecourt poster - spring"
campaign_refstring

Free-text tag the owning organisation groups and reports on.

Example:"spring-forecourt"
statusstring

INACTIVE refuses new redemptions and preserves every historical redemption.

Enum:"ACTIVE""INACTIVE"
Example:"ACTIVE"
limitationstringread-only

How many times the code may be redeemed.

Enum:"SINGLE_USE""SINGLE_USE_PER_USER""UNLIMITED"
Example:"UNLIMITED"
created_atstring, (date-time)read-only
Example:"2026-07-01T09:12:00Z"
performanceobject(ReferralCodePerformance)read-only

Redemption counts for one code, broken down by stage, from a single snapshot. Core computes in_progress_count rather than leaving a client to difference two reads, so all three numbers describe the same instant.

Response
{
  "id": "prom01JZQ8V5T7MKXR9NBCDEFGHJ4A",
  "url": "https://api.ev.energy/v2/referral_codes/prom01JZQ8V5T7MKXR9NBCDEFGHJ4A",
  "code": "SPRING24",
  "label": "Forecourt poster - spring",
  "campaign_ref": "spring-forecourt",
  "status": "ACTIVE",
  "limitation": "UNLIMITED",
  "created_at": "2026-07-01T09:12:00Z",
  "performance": {
    "redeemed_count": 64,
    "qualified_count": 41,
    "in_progress_count": 23
  }
}