public-api-docs

User API Vouchers And Promotions Guide

Overview

Vouchers and promotions explain why a user may receive a discount, credit, free minutes, or another rental benefit. Vouchers are issued to a user. Promotions are currently valid branch or geofence benefits that can affect discovery, rental pricing, package pricing, or end-rental behavior.

Use this guide for wallet voucher screens, voucher-code redemption, selected-vehicle voucher display, promotion maps, and discount explanations.

Related reference: User API User API Guide Discovery And Vehicle Guide Packages Guide Wallet And Balances Guide

Vouchers

Use GET /vouchers to list vouchers for the authenticated user. Common filters:

Filter Use
branchId Scope vouchers to a branch.
active=true with branchId Return active constraint vouchers for that branch.
constraint=true Return only constraint-type vouchers.
types / voucherType Filter by voucher source, such as package, subscription, reward, promotion, or single-use.

Important voucher fields:

Field Meaning
name, description, voucherableCode Display and campaign/template identity.
voucherType Source or product type behind the voucher.
status Active, expired, used up, canceled, pending, or not redeemed.
rentalRebate, rentalRebateNet Fixed rental rebate.
discount Percentage-style discount value.
valueGross, remainingValueGross Monetary credit value and remaining value.
freeMinutes, remainingFreeMinutes Minute entitlement and remaining minutes.
numberOfRentals, remainingNumberOfRentals Rental-count limits.
validFrom, validUntil Validity window.
applicablePriceType Target price component.

The app can decide how much of this to show. A compact wallet may show only name, remaining value/minutes, expiry, and status. A detailed benefit view can show price component, validity, and remaining rental count.

Show A Voucher Overview In The App

Use GET /vouchers for the user’s voucher overview or wallet benefit screen. The main job of this screen is to answer three questions:

  1. What is this voucher?
  2. What value does it still have?
  3. Where does it apply?

Start every voucher row with name, description, voucherType, status, and validUntil. Then choose the main value label from the benefit fields:

Voucher shape Fields to read Suggested user label
Wallet or credit value remainingValueGross, valueGross, currency €10 credit remaining
Free minutes remainingFreeMinutes, freeMinutes 30 free minutes remaining
Fixed rental rebate rentalRebate, rentalRebateNet, currency €2 off your rental
Percentage discount discount 20% discount
Rental count remainingNumberOfRentals, numberOfRentals 1 rental remaining
Addition entitlement additionEntitlementCode Includes helmet box or the addition name from your app catalog

Prefer remaining fields over original fields. For example, show remainingValueGross instead of valueGross, remainingFreeMinutes instead of freeMinutes, and remainingNumberOfRentals instead of numberOfRentals when the remaining value is present. The original fields explain what was granted; the remaining fields explain what the user can still use.

Then explain the target price component with applicablePriceType. A voucher can apply only to a specific cost source instead of the whole rental:

applicablePriceType What it applies to Suggested wording
TIME_PRICE General rental time cost. Applies to rental time
DRIVING_PRICE Driving time rate. Applies while driving
PARKING_PRICE Parking/paused rental rate. Applies while parked
DISTANCE_PRICE Distance-based price. Applies to distance charges
RESERVATION_PRICE Reservation price before the ride starts. Applies to reservation time
UNLOCK_FEE Unlock/start fee. Applies to the unlock fee

If applicablePriceType is empty, keep the wording broader, for example Applies to eligible rentals. If applicableBranchIds or vehicle-category constraints are available through the voucherable context, show the constraint in a details view rather than crowding the wallet row.

Discount values are fractional. For display, multiply by 100: 0.2 means 20% discount. A free-unlock voucher can be represented as discount=1 with applicablePriceType=UNLOCK_FEE; display that as Free unlock fee instead of 100% discount because it is clearer for users. Likewise, a voucher with discount=0.5 and applicablePriceType=DRIVING_PRICE should be displayed as 50% off driving time, not as a generic voucher.

Practical examples:

API values User-facing display
remainingValueGross=10, currency=EUR €10 wallet credit remaining
remainingFreeMinutes=30, applicablePriceType=TIME_PRICE 30 free rental minutes
discount=1, applicablePriceType=UNLOCK_FEE Free unlock fee
discount=0.2, applicablePriceType=DRIVING_PRICE 20% off driving time
rentalRebate=2, applicablePriceType=PARKING_PRICE €2 off parking time
remainingNumberOfRentals=1 1 eligible rental remaining

Example display logic:

for voucher in GET /vouchers:
  title = voucher.name
  status = voucher.status
  expiry = voucher.validUntil

  if remainingFreeMinutes is present:
    mainValue = "{remainingFreeMinutes} free minutes remaining"
  else if remainingValueGross is present:
    mainValue = "{remainingValueGross} {currency} credit remaining"
  else if rentalRebate is present:
    mainValue = "{rentalRebate} {currency} off"
  else if discount is present:
    if discount == 1 and applicablePriceType == UNLOCK_FEE:
      mainValue = "Free unlock fee"
    else:
      mainValue = "{discount * 100}% discount"
  else if remainingNumberOfRentals is present:
    mainValue = "{remainingNumberOfRentals} rental(s) remaining"

  appliesTo = labelFrom(applicablePriceType)

Use status and validity to decide visual treatment:

State UI treatment
ACTIVE Usable benefit. Show normally.
EXPIRED No longer usable. Grey out and show expiry.
USED_UP Fully consumed. Grey out and show “used”.
CANCELED No longer usable. Hide from compact wallet or show in history only.
PENDING / NOT_REDEEMED Not usable yet. Explain what the user needs to do, if applicable.

Do not present the wallet overview as a guarantee that a voucher will apply to the next trip. A voucher can still be limited by branch, vehicle category, validity, remaining value, cost source, rental state, package/subscription rules, and current pricing context. For a selected vehicle, use applicableVouchers from vehicle detail to show vehicle-specific eligibility.

Redeem Voucher Codes

Use POST /vouchers/redeem-code?code={code} for new clients. It returns all vouchers created from the redeemed voucherable. A single code can create multiple vouchers when the campaign has multiple benefits.

POST /vouchers/redeem is deprecated because it returns only the first created voucher.

After redemption:

  1. Re-fetch GET /vouchers.
  2. Re-fetch GET /balances if the voucher grants wallet value.
  3. Re-fetch selected vehicle detail if the user is already in a rental flow.

Selected Vehicle Voucher Display

For a selected vehicle, prefer vehicle.applicableVouchers from GET /vehicles/{id} or GET /vehicles/code/{code}. That list is filtered by the authenticated user, branch, and vehicle category. Use GET /vouchers for wallet views, not as the only source of selected-vehicle eligibility.

If multiple vouchers are eligible, present them as eligible benefits. The backend still decides the final applied voucher during pricing and billing.

Promotions

Use GET /promotions?branchId={branchId} to retrieve valid geofence promotions and surcharges for the current user. These are useful for map overlays and explaining price changes.

Promotion responses can include:

On vehicle maps, use GET /vehicles benefits to mark discounted/rewarded vehicles, then re-read the selected vehicle to show exact pricing.discount and applicableVouchers.

Most Relevant APIs

Area Endpoints
Voucher wallet GET /vouchers
Voucher redemption POST /vouchers/redeem-code, deprecated POST /vouchers/redeem
Promotions GET /promotions
Selected vehicle benefits GET /vehicles/{id}, GET /vehicles/code/{code}
Wallet value GET /balances, GET /balances/{balanceId}/history

Implementation Notes