Skip to content
/
List referral code redemp...

List referral code redemptions

Request

The per-redemption ledger for the caller organisation's codes, with the stage each redemption has reached.

Rows are anonymised: no email, name, phone, address or user id, and id is the redemption's own identifier, never the driver's. Because every row is scoped to a code the organisation owns and carries no identifier, figures are exact at every volume — a code with a single redemption reports one row.

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
referral_code_idstringprom[A-Z\d]{26}

Only return redemptions of this code. A code the caller's organisation does not own matches nothing.

Example:referral_code_id=prom01JZQ8V5T7MKXR9NBCDEFGHJ4A
stagestring

Only return redemptions that have reached this stage.

Enum:"REDEEMED""QUALIFIED"
redeemed_at__gtestring, (date-time)

Only return redemptions made at or after this time.

redeemed_at__ltestring, (date-time)

Only return redemptions made at or before this time.

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_code_redemptions?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10&referral_code_id=prom01JZQ8V5T7MKXR9NBCDEFGHJ4A&stage=REDEEMED&redeemed_at__gte=2019-08-24T14%3A15%3A22Z&redeemed_at__lte=2019-08-24T14%3A15%3A22Z' \
  -H 'Accept-Language: string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns the anonymised redemption rows.

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 [
idstringprdm[A-Z\d]{26}read-onlyrequired

Unique identifier for the redemption. Never the driver's identifier.

Example:"prdm01JZQ8V5T7MKXR9NBCDEFGHJ4B"
urlstring, (uri)read-onlyrequired
Example:"https://api.ev.energy/v2/referral_code_redemptions/prdm01JZQ8V5T7MKXR9NBCDEFGHJ4B"
referral_codestring, (uri)read-only

Reference to the code that was redeemed.

Example:"https://api.ev.energy/v2/referral_codes/prom01JZQ8V5T7MKXR9NBCDEFGHJ4A"
codestringread-only

The code string, denormalised so a ledger renders without a second read.

Example:"SPRING24"
stagestringread-onlyrequired

REDEEMED — the driver signed up with the code. QUALIFIED — the driver has since completed the qualifying charge, which is what earns commission.

Enum:"REDEEMED""QUALIFIED"
Example:"QUALIFIED"
redeemed_atstring, (date-time)read-only
Example:"2026-07-10T08:30:00Z"
qualified_atstring or null, (date-time)read-only

When the qualifying charge finished. Null while the redemption is still in progress, and also on a QUALIFIED redemption whose qualifying session has no recorded finish time.

Example:"2026-07-18T19:04:00Z"
]
Response
[
  {
    "id": "prdm01JZQ8V5T7MKXR9NBCDEFGHJ4B",
    "url": "https://api.ev.energy/v2/referral_code_redemptions/prdm01JZQ8V5T7MKXR9NBCDEFGHJ4B",
    "referral_code": "https://api.ev.energy/v2/referral_codes/prom01JZQ8V5T7MKXR9NBCDEFGHJ4A",
    "code": "SPRING24",
    "stage": "QUALIFIED",
    "redeemed_at": "2026-07-10T08:30:00Z",
    "qualified_at": "2026-07-18T19:04:00Z"
  }
]