Skip to content

List referral codes

Request

List the referral/promo codes owned by the caller's organisation, each with its redemption counts broken down by stage.

The organisation comes from the credential, never from a query parameter: a Clerk session token carries exactly one active organization, and that is the tenant. Codes with no owning organisation (globally administered promo codes) are never returned.

Security
oauth2(Required scopes: referral:read)
Query
page_beforestring[a-z]{4}[A-Z\d]{26}

Return results from the page after this ID.

Example:page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR
page_afterstring[a-z]{4}[A-Z\d]{26}

Return results from the page before this ID.

Example:page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR
page_sizeinteger, [ 1 .. 100 ]

Specify the number of results to return per page.

Default:25
Example:page_size=10
statusstring

Only return codes in this status.

Enum:"ACTIVE""INACTIVE"
campaign_refstring

Only return codes carrying this campaign tag.

Example:campaign_ref=spring-forecourt
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.

curl -i -X GET \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/referral_codes?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10&status=ACTIVE&campaign_ref=spring-forecourt' \
  -H 'Accept-Language: string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns the organisation's referral codes.

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
X-RateLimit-Limitnumber

The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

Default:1000
X-RateLimit-Remainingnumber

The number of requests remaining until this client's rate limit is reached.

Default:999
RetryAfternumber

The number of seconds until this client's requests will not be rate limited.

Default:3600
Bodyapplication/json
Array [
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": { … }
  }
]