# List incentives

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.

Endpoint: GET /incentives
Version: 2.0
Security: oauth2

## Security:

  - `oauth2` (unknown)
    oauth2 scopes: incentives:read

## Query parameters:

  - `page_before` (string)
    Return results from the page after this ID.

  - `page_after` (string)
    Return results from the page before this ID.

  - `page_size` (integer)
    Specify the number of results to return per page.

  - `user_id` (string)
    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.

  - `scheme_id` (string)
    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.

  - `status` (array)
    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_from` (string)
    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.

  - `period_to` (string)
    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.

  - `include_adjustments` (boolean)
    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.

  - `include_zero` (boolean)
    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.

  - `expand` (array)
    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`.

## Header parameters:

  - `EvEnergy-Version` (number)
    Specify the version of this endpoint to use.

  - `Accept-Language` (string)
    Indicates the natural language and locale that the client prefers.

## Response 200:

  - `200` (unknown)
    Returns a list of incentives, sorted newest recorded first.

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique identifier for the incentive. It sorts by when the incentive was recorded.

  - `user` (any, required)
    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.

  - `user.id` (string, required)
    Unique identifier for the given user.
    Example: user01HN2NJ9NMRZBXT1H6FT9N7735

  - `user.url` (string, required)
    Example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735

  - `user.email` (string)

  - `user.full_name` (string)
    The user's full name.
    Example: Frodo Baggins

  - `user.joined_at` (string)
    The date and time when the user joined the platform.
    Example: 2023-06-15T10:00:00Z

  - `user.terms_consent_datetime` (string | null)
    When the user gave their terms and conditions consent, or null if they have not.
    Example: 2023-06-15T10:00:00Z

  - `user.deleted_at` (string | null)
    When the user's account was deleted, or null if it is still live. Deleted accounts are anonymised, so the remaining fields hold placeholder values rather than the user's data, except `enrollment_status`, `tier_enrolled_at` and `left_at`, which keep their real enrollment history. Reaching a deleted user requires `include_deleted=true`.
    Example: 2024-08-01T12:00:00Z

  - `user.referral_code` (string | null)
    This user's personal referral code.
    Example: FRODO1

  - `user.referral_performance` (object)
    How the users who signed up with this user's referral code have progressed,
broken down by stage like a promo code's `performance`. `rewarded_count` counts
referrals this user has been credited for, whether or not the credit has been
paid out yet. `qualified_count` ignores the referral scheme's membership, region
and active-window rules and any cap on the referrer's rewards, so it can be
higher than `rewarded_count`.

  - `user.referral_performance.redeemed_count` (integer, required)
    Users who signed up with this user's referral code.
    Example: 3

  - `user.referral_performance.qualified_count` (integer, required)
    Of those, the users who have finished a charging session of at least 1 kWh.
    Example: 2

  - `user.referral_performance.in_progress_count` (integer, required)
    `redeemed_count` minus `qualified_count`, clamped at zero.
    Example: 1

  - `user.referral_performance.rewarded_count` (integer, required)
    Referrals this user has been credited for with a value above zero.
    Example: 1

  - `user.deleted` (boolean)
    Whether the user's account has been deleted. True exactly when `deleted_at` is set.
    Example: false

  - `user.enrollment_status` (string | null)
    The user's standing in your programs: `ENROLLED` while they hold an open enrollment in one of them, `LEFT` once their latest enrollment has ended, or null if they have never enrolled in any of them.
    Enum: "ENROLLED", "LEFT", "null"

  - `user.tier_enrolled_at` (string | null)
    When the enrollment behind `enrollment_status` began, or null if the user has never enrolled in one of your programs.
    Example: 2024-01-10T14:30:00Z

  - `user.left_at` (string | null)
    When the enrollment behind `enrollment_status` ended, or null while it is open or if the user has never enrolled in one of your programs.
    Example: null

  - `user.program` (any)
    The program of the enrollment behind `enrollment_status`, or null if the user has never enrolled in one of your programs. Defaults to a url, but can be expanded to the full Program resource via the `expand` query parameter.

  - `user.program.id` (string)
    Example: prog01JCK1HPNAANB8WN253G27SFPC

  - `user.program.url` (string)
    Example: https://api.ev.energy/v2/programs/prog01JCK1HPNAANB8WN253G27SFPC

  - `user.program.name` (string)
    A human-friendly name for the Program.
    Example: CoolCharge

  - `user.program.description` (string)
    A plain text description of the program's incentives and requirements.
    Example: A program which incentivises charging when it's coolest to charge your EV

  - `user.program.logo` (string | null)
    URL to download a logo image for the Program.

  - `user.program.sponsor_name` (string)
    The name of the organisation which sponsors the program. Often, but not always, a utility company.
    Example: Cool Power

  - `user.program.external_url` (string)
    A publicly accessible URL where individuals can enroll in the program.
    Example: https://www.example.com/coolcharge

  - `user.program.sign_up_url` (string | null)
    URL of the registration form for this specific program, where one exists.
    Example: https://www.example.com/coolcharge/sign-up

  - `user.program.eligibility_criteria` (string | null)
    HTML description of who is eligible to join the program.
    Example: <html><p>Residential customers of Cool Power with a compatible EV or home charger.</p></html>

  - `user.program.benefits` (string | null)
    HTML description of the benefits of joining the program.
    Example: <html><p>Earn a monthly bill credit for charging off-peak.</p></html>

  - `user.program.country` (string)
    ISO 3166-1 alpha-2 code of the country the program operates in.
    Example: US

  - `user.program.faqs_url` (string | null)
    URL of the program's FAQ page, where one exists.
    Example: https://www.example.com/coolcharge/faqs

  - `user.program.support_email` (string)
    Customer support email address for this program.
    Example: support@ev.energy

  - `user.program.payment_frequency` (string | null)
    How often incentive payments are made, where the program pays incentives.
    Enum: "WEEKLY", "MONTHLY", "QUARTERLY", "null"

  - `user.program.payment_day_of_month` (integer | null)
    Day of the month incentive payments are made, for monthly or quarterly programs. 31 means the last day of the month. Null when the program has no payment day configured.
    Example: 15

  - `user.program.payment_weekday` (string | null)
    Day of the week incentive payments are made, for weekly programs. Null when the program has no payment weekday configured.
    Enum: "MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN", "null"

  - `user.program.hidden` (boolean)
    Whether the program is hidden from public program lists. Hidden programs (test, internal, ended or mothballed) are omitted from the list endpoint for anonymous and driver-scoped requests, but are still returned by ID and are always listed for organisation-scoped API clients.
    Example: false

  - `user.tier` (any)
    The tier of the enrollment behind `enrollment_status`, or null if the user has never enrolled in one of your programs. Defaults to a url, but can be expanded to the full ProgramTier resource via the `expand` query parameter. A hidden tier is still linked, and still embedded when expanded, but its url returns 404. An expanded tier's `eligible` describes the requesting user (or the driver acted as via `EvEnergy-User`), not necessarily this user.

  - `user.tier.id` (string)
    Example: tier01JCK1HPNAANB8WN253G27SFPC

  - `user.tier.url` (string)
    Example: https://api.ev.energy/v2/programs/prog01JCK1HPNAANB8WN253G27SFPC/tiers/tier01JCK1HPNAANB8WN253G27SFPC

  - `user.tier.short_name` (string)
    A short slug-style identifier for the tier, unique within a program.
    Example: standard

  - `user.tier.name` (string | null)
    A human-friendly name for the tier.
    Example: Standard Tier

  - `user.tier.logo_svg` (string | null)
    URL to download an SVG logo for the tier.

  - `user.tier.description_short` (string | null)
    Short HTML description of the tier. Wrapped in `<html>` tags on both real and sandbox responses.

  - `user.tier.description_long` (string | null)
    Longer HTML description of the tier. Wrapped in `<html>` tags on both real and sandbox responses.

  - `user.tier.smart_charging_enabled` (boolean)
    Whether smart charging is enabled for users in this tier.

  - `user.tier.disable_changing_tariff` (boolean)
    Whether users in this tier are blocked from changing their tariff.

  - `user.tier.visible` (boolean)
    Whether this tier should be shown to users when selecting a tier within the program.

  - `user.tier.eligible` (boolean | null)
    Whether the authenticated user is eligible to join this tier. Populated only when
the request is authenticated as a specific user (Authorization Code / Password grant,
or Client Credentials with the `EvEnergy-User` header). A Clerk active-organisation
session acting as a driver via `EvEnergy-User` gets that driver's eligibility.
`null` for anonymous and pure client-credentials requests.

  - `user.default_location` (any)
    LocationDetail is served when a single user is requested, otherwise Location is served for user lists.

  - `user.default_location.address_1` (string | null)
    First line of address.

  - `user.default_location.address_2` (string | null)
    Second line of address.

  - `user.default_location.postal_code` (string | null)
    Postal Code.

  - `user.default_location.country_code` (string)
    ISO 3166-1 2 letter Country Codes.
    Enum: "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW"

  - `user.default_location.coordinates` (any)

  - `user.default_location.coordinates.latitude` (number, required)
    Example: 51.52576576674041

  - `user.default_location.coordinates.longitude` (number, required)
    Example: -0.08366433371722264

  - `user.default_location.tariff` (any)
    The import tariff at this location. When updating, it must be a tariff visible to you: a public tariff or one of your organisation's custom tariffs. Renders as `null` if the tariff is another organisation's custom tariff.

  - `user.default_location.tariff.id` (string, required)
    Unique identifier for the given user.
    Example: tari01HN2NJ9NMRZBXT1H6FT9N7735

  - `user.default_location.tariff.url` (string, required)
    Example: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735

  - `user.default_location.tariff.supplier` (any, required)
    The energy company that supplies this tariff.

  - `user.default_location.tariff.supplier.id` (string, required)
    Unique identifier for the given user.
    Example: supl01HN2NJ9NMRZBXT1H6FT9N7735

  - `user.default_location.tariff.supplier.url` (string, required)
    Example: https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735

  - `user.default_location.tariff.supplier.name` (string, required)
    Example: Rivendell Renewables

  - `user.default_location.tariff.supplier.icon` (string | null, required)
    Example: https://cdn.example.com/rivendell_renewables.jpg

  - `user.default_location.tariff.supplier.highlighted` (boolean)
    A highlighted supplier is one that is often selected by users.

  - `user.default_location.tariff.name` (string, required)
    Example: Fangorn Biomass

  - `user.default_location.tariff.currency` (string, required)
    Example: GBP

  - `user.default_location.tariff.highlighted` (boolean)
    A highlighted tariff is one that is often selected by users.

  - `user.default_location.tariff.type` (string)
    Enum: "FLAT_RATE", "DUAL_RATE", "THREE_RATE", "DYNAMIC", "EXTERNALLY_MANAGED", "OTHER"

  - `user.default_location.tariff.daily_prices` (object)
    Information about the tariff's prices for different parts of the day.

  - `user.default_location.tariff.daily_prices.peak` (object, required)
    A single price for a certain time range.

  - `user.default_location.tariff.daily_prices.peak.price` (string | null)
    The price is in major currency units e.g. 0.10 means £0.10. `null` for licensed tariffs without the tariff:prices:read scope.
    Example: 0.10

  - `user.default_location.tariff.daily_prices.peak.times` (array)

  - `user.default_location.tariff.timezone_name` (string)
    Example: Europe/London

  - `user.default_location.tariff.price_chart_url` (string | null)
    The url of a website which can display a chart of prices for the tariff. This website is an external resource and is not affiliated with ev.energy.
    Example: https://www.example.com/

  - `user.default_location.tariff.prices_include_vat` (boolean | null)
    Whether the prices of this tariff include VAT. `null` if this is not known for the tariff.
    Example: true

  - `user.default_location.tariff.gsp_group` (string | null)
    The GB Grid Supply Point (DNO region) the tariff applies to. Suppliers publish region-specific rates, so the same named tariff can appear once per region with differing prices; this field distinguishes them. `null` for tariffs that are not region-specific.
    Example: _C

  - `user.default_location.tariff.valid_from` (string)
    The date from which this tariff became available to new customers.
    Example: 2026-03-17

  - `user.default_location.tariff.valid_until` (string | null)
    The date after which this tariff is no longer available to new customers (it has been superseded). `null` if the tariff is still open to new sign-ups. Use the `valid` query parameter to filter the list to only currently-available tariffs.
    Example: 2027-03-17

  - `user.default_location.tariff.payment_method` (string | null)
    The payment method the tariff's prices apply to. Some suppliers charge different rates depending on how the customer pays, so the same named tariff can appear once per payment method; this field distinguishes them. `null` when the supplier does not price by payment method.
    Enum: "DIRECT_DEBIT", "NON_DIRECT_DEBIT", "null"

  - `user.default_location.tariff.scheduler_tariff` (any)
    The tariff used by the scheduler for charge optimisation, which may differ from the billing tariff. Returns a URL by default, or null if not set. Expandable with ?expand=scheduler_tariff to return a TariffBase object (additional fields may be present beyond those listed here).

  - `user.default_location.tariff.scheduler_tariff.id` (string, required)

  - `user.default_location.tariff.scheduler_tariff.url` (string, required)

  - `user.default_location.tariff.scheduler_tariff.supplier` (string, required)

  - `user.default_location.tariff.scheduler_tariff.name` (string, required)

  - `user.default_location.tariff.scheduler_tariff.currency` (string, required)

  - `user.default_location.city` (string | null)

  - `user.default_location.state` (string | null)

  - `user.default_location.evse_site` (any)
    If null, the user's location is not an EVSE Site. Otherwise, this field references the site they are a part of.

  - `user.default_location.evse_site.id` (string, required)

  - `user.default_location.evse_site.url` (string, required)
    Example: https://api.ev.energy/v2/evse_sites/site01JX2SZ0WAFTDYVYY0JRAYREY7

  - `user.default_location.evse_site.evses` (array, required)
    A list of all EVSEs that are currently associated with this site.

  - `user.default_location.evse_site.cpms_connection` (string | null, required)
    The type of ChargePoint Management System that this site is connected to, if there is one.
    Enum: "null", "CHARGEPOINT", "SWTCH"

  - `user.default_location.evse_site.cpms_connection_display_name` (string | null)
    A human-readable name for the Chargepoint Management System that the site is connected to.
    Example: ChargePoint

  - `user.default_location.evse_site.user_connected` (boolean | null)
    When authenticated as a specific user (eg. via the Authorisation Code grant type) or when the EvEnergy-User header is set to a valid user ID, this field will indicate whether the user is currently connected to this EVSE Site's CPMS. If the request is not made in the context of a user, or the site does not have a CPMS connection, this field will be null.

  - `user.default_location.current_carbon_intensity_grams_per_kilowatt_hour` (integer | null)
    The current carbon intensity associated with the location in gCO2/kWh.
    Example: 300

  - `user.vehicles` (array)

  - `user.evses` (array)

  - `scheme` (any, required)
    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.

  - `scheme.id` (string, required)
    Unique identifier for the incentive scheme.

  - `scheme.name` (string | null, required)
    Name shown to drivers, in the `Accept-Language` language where a translation exists.

  - `scheme.description` (string | null, required)
    How a driver earns the incentive, in the `Accept-Language` language where a translation exists.

  - `scheme.visible` (boolean, required)
    Whether the scheme is shown to drivers in the app.

  - `scheme.scheme_type` (string, required)
    The scheme's sub-type, for example `REFERRAL`. Every other scheme reads `STANDARD`. New values may be added over time.

  - `period_month` (string, required)
    The month, `YYYY-MM`, the incentive was recorded in, in the scheme's timezone.

  - `period_start` (string | null, required)
    Start of the period the incentive covers. Null for a one-off incentive.

  - `period_end` (string | null, required)
    End of the period the incentive covers. Null for a one-off incentive.

  - `amount` (integer | null, required)
    The incentive's value in the minor unit of `currency`, for example cents for USD. Null when no value was recorded.

  - `currency` (string | null, required)
    ISO 4217 code of the currency `amount` is in.

  - `rationale` (string | null, required)
    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_adjustment` (boolean, required)
    True for a correction to a period that was already processed.

  - `payout_status` (string, 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"

  - `payout_status_detail` (string, 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", "NOT_PAYABLE"

  - `paid_at` (string | null, required)
    When PayPal processed a successful payment of the incentive. Null otherwise.

  - `batched_at` (string | null, 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_visibility` (string, 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"

## Response 200 headers (application/json):

  - `Link` (string)
    Provides links to the previous and next pages of data, if they exist.
    Example: <https://api.ev.energy/v2/vehicles?page_size=25&page_before=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H>; rel="previous", <https://api.ev.energy/v2/vehicles?page_size=25&page_after=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H>;…

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

  - `RetryAfter` (number)
    The number of seconds until this client's requests will not be rate limited.

## Response 400:

  - `400` (unknown)
    A problem with the request's parameters prevented it being fulfilled. This endpoint rejects query parameters it does not read, and values it cannot parse.

## Response 400 fields (application/problem+json):

  - `type` (string)
    Example: https://api.ev.energy/v2/problems/example-problem/

  - `status` (number)
    Example: 400

  - `title` (string, required)
    Example: Short description

  - `detail` (string, required)
    Example: Long, more specific description.

  - `instance` (string)
    Example: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E

  - `notification` (object)
    Something that the user should be informed about.

  - `notification.id` (string, required)
    Unique identifier for the Notification
    Example: notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.url` (string, required)
    Example: https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.message_id` (string, required)
    Internal identifier for this notification type. E.g. 'ERR0023'

  - `notification.category` (string, required)
    Category of this notification type
    Enum: "ACTIONABLE", "SERVICE", "RETRY", "MARKETING", "INTERNAL"

  - `notification.event_time` (string, required)
    The timestamp of the event described by this notification

  - `notification.short_text_title` (string, required)
    Short title for the notification

  - `notification.short_text_body` (string, required)
    Short description of the event being notified

  - `notification.detail_page_title` (string, required)
    Title of a help page giving more information about this notification

  - `notification.detail_page_body` (string, required)
    Text of a help page giving more information about this notification

  - `notification.external_link` (string | null, required)
    URL of a web page giving further information about this notification

  - `notification.external_button_label` (string, required)
    Text to be displayed on a button leading to the external_link location

  - `notification.read_at` (string)
    When the user examined the contents of this notification

  - `notification.resolved_at` (string)
    When the problem associated with this notification was resolved

## Response 400 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

  - `RetryAfter` (number)
    The number of seconds until this client's requests will not be rate limited.

## Response 401:

  - `401` (unknown)
    You need to authorise requests to access this resource.

## Response 401 fields (application/problem+json):

  - `status` (number)
    Example: 401

  - `title` (string, required)
    Example: Unauthorized

  - `detail` (string, required)
    Example: Authentication credentials were not provided.

## Response 401 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

  - `RetryAfter` (number)
    The number of seconds until this client's requests will not be rate limited.

## Response 403:

  - `403` (unknown)
    You do not have permission to perform this action.

## Response 403 fields (application/problem+json):

  - `status` (number)
    Example: 403

  - `title` (string, required)
    Example: Forbidden

  - `detail` (string, required)
    Example: You do not have permission to perform this action.

## Response 403 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

  - `RetryAfter` (number)
    The number of seconds until this client's requests will not be rate limited.

## Response 406:

  - `406` (unknown)
    Could not satisfy the request Accept header.

## Response 406 fields (application/problem+json):

  - `status` (number)
    Example: 406

  - `title` (string, required)
    Example: Not Acceptable

  - `detail` (string, required)
    Example: Could not satisfy the request Accept header.

## Response 406 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

  - `RetryAfter` (number)
    The number of seconds until this client's requests will not be rate limited.

## Response 429:

  - `429` (unknown)
    The client has exceeded its rate limit.

## Response 429 fields (application/problem+json):

  - `type` (string)
    Example: https://api.ev.energy/v2/problems/example-problem/

  - `status` (number)
    Example: 400

  - `title` (string, required)
    Example: Short description

  - `detail` (string, required)
    Example: Long, more specific description.

  - `instance` (string)
    Example: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E

  - `notification` (object)
    Something that the user should be informed about.

  - `notification.id` (string, required)
    Unique identifier for the Notification
    Example: notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.url` (string, required)
    Example: https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.message_id` (string, required)
    Internal identifier for this notification type. E.g. 'ERR0023'

  - `notification.category` (string, required)
    Category of this notification type
    Enum: "ACTIONABLE", "SERVICE", "RETRY", "MARKETING", "INTERNAL"

  - `notification.event_time` (string, required)
    The timestamp of the event described by this notification

  - `notification.short_text_title` (string, required)
    Short title for the notification

  - `notification.short_text_body` (string, required)
    Short description of the event being notified

  - `notification.detail_page_title` (string, required)
    Title of a help page giving more information about this notification

  - `notification.detail_page_body` (string, required)
    Text of a help page giving more information about this notification

  - `notification.external_link` (string | null, required)
    URL of a web page giving further information about this notification

  - `notification.external_button_label` (string, required)
    Text to be displayed on a button leading to the external_link location

  - `notification.read_at` (string)
    When the user examined the contents of this notification

  - `notification.resolved_at` (string)
    When the problem associated with this notification was resolved

## Response 429 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `Retry-After` (number)
    The number of seconds until this client's requests will not be rate limited.

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

## Response 400 examples:

  - `Invalid Pagination Parameter` (unknown)

  - `Unsupported Version` (unknown)

  - `Unknown Query Parameter` (unknown)

  - `Invalid Query Parameter Value` (unknown)

## Response 429 examples:

  - `Example 1` (unknown)