Skip to content

Incentives

Endpoints for the incentives participants earn under an organisation's programs.

Operations

List incentives

Request

List the incentives an organisation's participants earned under its programs, newest recorded first.

An incentive is visible to an organisation when its scheme belongs to one of the organisation's programs. A participant who moves to another organisation's program leaves their earlier incentives with the organisation they were earned under. An incentive whose scheme has no program, or that has no scheme, is never returned.

Only organisation-scoped callers see incentives, such as a client credentials token linked to an organisation. A user token, or an organisation token sent with an EvEnergy-User header, returns an empty list.

By default the list leaves out adjustments (is_adjustment is true) and zero-value incentives. include_adjustments and include_zero add them back. Every other filter narrows the list, and an incentive must match all the filters set.

An unknown query parameter, a value a parameter cannot parse, or any filter other than status sent more than once, returns a 400 problem.

expand=scheme and expand=user inline the linked scheme and participant. Send each as its own expand parameter (?expand=scheme&expand=user); a comma-joined value returns a 400 problem. An expanded user reads as null once the participant is no longer a member of the organisation; unexpanded it stays their URL, and their incentive stays in the list.

Security
oauth2(Required scopes: incentives: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
user_idstring^user[0-7][0-9A-HJKMNP-TV-Z]{25}$

Filter incentives to one participant, given as a User ID from /users, not an internal numeric ID. A participant who has since left your programs still matches the incentives they earned under them. A User ID with no incentives you can see, including one that does not exist, yields an empty page. Any other value, including an empty one or me, will be rejected with an invalid-query-parameter-value problem.

Example:user_id=user01J9X4K2M7Q8R3T5V6W7Y8Z9A0
scheme_idstring^incs[0-7][0-9A-HJKMNP-TV-Z]{25}$

Filter incentives to one scheme, given as an Incentive Scheme ID. A scheme outside your programs, including one that does not exist, yields an empty page. Any other value, including an empty one or a numeric ID, will be rejected with an invalid-query-parameter-value problem.

Example:scheme_id=incs01HZ8Y7X6W5V4A3T2S1R0Q9P8N
statusArray of strings

Filter incentives by payout_status. Repeat the parameter to match any of several statuses, for example status=NEEDS_ATTENTION&status=UNSETTLED. The filter reads the same value as the payout_status field, so every incentive returned carries one of the requested statuses. NOT_PAYABLE still respects the default view: it returns zero-value incentives and adjustments only when include_zero or include_adjustments is also set. Any other value will be rejected with an invalid-query-parameter-value problem.

period_fromstring^[1-9]\d{3}-(0[1-9]|1[0-2])$

Filter incentives to those whose period_month is this month or later, as YYYY-MM. Each month is bounded in its scheme's timezone. Any other format will be rejected with an invalid-query-parameter-value problem.

Example:period_from=2026-01
period_tostring^[1-9]\d{3}-(0[1-9]|1[0-2])$

Filter incentives to those whose period_month is this month or earlier, as YYYY-MM. Each month is bounded in its scheme's timezone. A period_to before period_from yields an empty page. Any other format will be rejected with an invalid-query-parameter-value problem.

Example:period_to=2026-08
include_adjustmentsboolean

Include adjustments, the incentives whose is_adjustment is true. They are left out by default. Send true or false; an empty value counts as absent. Other spellings, such as yes or 1, will be rejected with an invalid-query-parameter-value problem.

Default:false
Example:include_adjustments=true
include_zeroboolean

Include incentives whose amount is zero or null. They are left out by default. Send true or false; an empty value counts as absent. Other spellings, such as yes or 1, will be rejected with an invalid-query-parameter-value problem.

Default:false
Example:include_zero=true
expandArray of strings

Specify a url field to expand into a nested resource. Expanding user needs the user:read scope as well. The expanded scheme's name and description follow the Accept-Language header, as on /incentive_schemes.

Items Enum:"scheme""user"
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/incentives?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10&user_id=user01J9X4K2M7Q8R3T5V6W7Y8Z9A0&scheme_id=incs01HZ8Y7X6W5V4A3T2S1R0Q9P8N&status=NEEDS_ATTENTION&period_from=2026-01&period_to=2026-08&include_adjustments=true&include_zero=true&expand=scheme' \
  -H 'Accept-Language: string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns a list of incentives, sorted newest recorded first.

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

Unique identifier for the incentive. It sorts by when the incentive was recorded.

userstring or User (object) or nullrequired
One of:

URL of the participant who earned the incentive, or the participant itself with ?expand=user. Expanded, it is null once the participant is no longer a member of the calling organisation, because they left it or moved to another organisation.

string (uri)
schemestring or IncentiveSchemeSummary (object)required
One of:

URL of the incentive scheme the incentive was earned under, or the scheme itself with ?expand=scheme. The URL names the scheme by its incs id; the API does not yet serve a single incentive scheme at it.

string (uri)
period_monthstring^\d{4}-\d{2}$required

The month, YYYY-MM, the incentive was recorded in, in the scheme's timezone.

period_startstring or null, (date-time)required

Start of the period the incentive covers. Null for a one-off incentive.

period_endstring or null, (date-time)required

End of the period the incentive covers. Null for a one-off incentive.

amountinteger or nullrequired

The incentive's value in the minor unit of currency, for example cents for USD. Null when no value was recorded.

currencystring or null^[A-Z]{3}$required

ISO 4217 code of the currency amount is in.

rationalestring or nullrequired

Why the incentive was recorded. Null for incentives recorded before a reason was kept.

Enum:"CHARGING_SESSION_COMPLETED""CHARGED_OFF_PEAK""PARTICIPATED_IN_REQUIRED_EVENTS""PROCESSED_EVENTS_FOR_PERIOD""ADJUSTMENT_FOR_PERIOD""PARTICIPATED_IN_ALL_LINKED_SCHEMES""DID_NOT_PARTICIPATE_IN_ALL_LINKED_SCHEMES""SET_TO_ZERO_MAX_REWARDS_REACHED"null
is_adjustmentbooleanrequired

True for a correction to a period that was already processed.

payout_statusstring(IncentivePayoutStatus)required

Whether the incentive has been paid, derived from payout_status_detail.

  • SETTLED: paid, or as settled as ev.energy can tell (PAID, PAID_EXTERNALLY, SENT_TO_UTILITY).
  • UNSETTLED: earned and on track, no action needed (SCHEDULED, BATCHED).
  • NEEDS_ATTENTION: earned but stuck, support should act (BLOCKED, FAILED, RETURNED, ON_HOLD, UNCLAIMED).
  • NOT_PAYABLE: nothing to pay (NOT_PAYABLE).
Enum:"SETTLED""UNSETTLED""NEEDS_ATTENTION""NOT_PAYABLE"
Example:"NEEDS_ATTENTION"
payout_status_detailstring(IncentivePayoutStatusDetail)required

The fine-grained payout status, for investigating one incentive.

  • PAID: PayPal paid the participant.
  • PAID_EXTERNALLY: marked as paid outside ev.energy.
  • SENT_TO_UTILITY: sent to the utility to credit the participant's bill. ev.energy does not confirm the credit reached the bill.
  • BATCHED: in a payout that has not completed.
  • SCHEDULED: due to be added to the next payout.
  • BLOCKED: held by ev.energy, because the participant has no payout method or must be verified first.
  • FAILED: the payment failed.
  • RETURNED: the payment was returned, refunded or reversed.
  • ON_HOLD: PayPal is holding the payment.
  • UNCLAIMED: the participant has not claimed the PayPal payment.
  • NOT_PAYABLE: nothing to pay, because the value is missing, zero or negative, the incentive is an adjustment or excluded from payouts, or ev.energy does not pay the scheme.
Enum:"PAID""PAID_EXTERNALLY""SENT_TO_UTILITY""BATCHED""SCHEDULED""BLOCKED""FAILED""RETURNED""ON_HOLD""UNCLAIMED"
Example:"RETURNED"
paid_atstring or null, (date-time)required

When PayPal processed a successful payment of the incentive. Null otherwise.

batched_atstring or null, (date-time)required

When the incentive was added to a payout. After a failed or returned PayPal payment, when it was added to the payout that failed. Null if it was never added to one.

driver_visibilitystring(IncentiveDriverVisibility)required

Whether, and how, the participant sees the incentive in the ev.energy app.

  • VISIBLE: the app shows the incentive.
  • UNRELEASED_MONTH: the month has not been released to participants yet.
  • SHOWN_AS_EVENTS: the scheme shows earnings as in-month events, so the participant sees the earning but never this incentive.
  • HIDDEN: the scheme is not shown in the app, or the incentive is a hidden adjustment.
Enum:"VISIBLE""UNRELEASED_MONTH""SHOWN_AS_EVENTS""HIDDEN"
Example:"VISIBLE"
]
Response
[
  {
    "id": "inct01JA2B3C4D5E6F7G8H9J0K1N2M",
    "user": "https://api.ev.energy/v2/users/user01J9X4K2M7Q8R3T5V6W7Y8Z9A0",
    "scheme": "https://api.ev.energy/v2/incentive_schemes/incs01HZ8Y7X6W5V4A3T2S1R0Q9P8N",
    "period_month": "2026-08",
    "period_start": "2026-08-01T04:00:00Z",
    "period_end": "2026-09-01T04:00:00Z",
    "amount": 2500,
    "currency": "USD",
    "rationale": "PROCESSED_EVENTS_FOR_PERIOD",
    "is_adjustment": false,
    "payout_status": "NEEDS_ATTENTION",
    "payout_status_detail": "RETURNED",
    "paid_at": null,
    "batched_at": "2026-08-15T14:02:11Z",
    "driver_visibility": "SHOWN_AS_EVENTS"
  }
]