public-api-docs

Operations API Promotions, Packages, Subscriptions, And Benefits Guide

Overview

Promotions, packages, subscriptions, ride passes, customer-care credit, rewards, referral benefits, and geofence surcharges are managed through a shared technical model. In the API this model is called a voucherable: a template that can issue vouchers, grant benefits, apply discounts, create wallet credit, or modify rental pricing.

Because “voucherable” is an internal technical term, operator tooling should normally describe these objects by their business purpose: promotion, package, subscription, ride pass, customer-care credit, reward, referral benefit, or surcharge.

Use this guide when building operator tools for promotion codes, package catalogs, subscription plans, customer-care credit templates, user subscription review, redeemable code campaigns, or rental price benefits.

Related reference: Operations API

Operations API Guide

Pricing Guide

Payments And Invoices Guide

Customers And Groups Guide

Error Codes

Core Concepts

Catalog Template And Issued Voucher

The model has two levels:

Concept	API term	Meaning
Catalog template	`voucherable`	The configured product, campaign, subscription plan, reward, customer-care template, or surcharge rule.
Issued benefit	`voucher` / `constraint voucher`	The concrete value, discount, entitlement, or rule instance held by a customer or business account.

For example, a promotion campaign is the template. When a customer redeems the promotion code, the customer receives one or more issued vouchers based on the template’s benefits.

Available Template Types

The type field on ConstraintVoucherable identifies the business behavior:

Type	Business meaning
`Promotion`	A redeemable promotion, usually entered as a promotion code.
`GeoFencePromotion`	A promotion that applies when a rental starts or ends in a configured geofence.
`Package`	A one-time paid product that grants credit, minutes, discounts, or other benefits.
`Subscription`	A recurring paid product that renews on an interval and grants benefits.
`Reward`	A reward granted after a usage condition is met.
`SignupReferral`	Signup/referral benefit template for referrers and referees.
`Triggered`	A benefit triggered by a configured event, such as a ride reward or cashback.
`CustomerCare`	A support template used by operators to grant goodwill credit or benefits.
`VehiclePromotion`	A promotion targeted at specific vehicles.
`GeoFenceSurcharge`	A surcharge applied when a rental starts or ends in a configured geofence.
`RidePass`	A paid pass that grants a fixed rental, value, or time benefit.
`PricedPromotion`	A paid promotion product.

Most new tooling should use the /voucherables endpoints for template management. Legacy /packages and /subscriptions endpoints still exist in the API, but they are deprecated and should not be the default for new integrations.

Benefits

A benefit defines what the template grants. Modern templates can contain multiple benefits.

Benefit type	Meaning
`Value`	Monetary credit.
`Discount`	Percentage discount, represented as a decimal fraction between `0` and `1`.
`RentalRebate`	Fixed amount reduction for a rental.
`FreeUnlocks`	Free unlocks.
`DiscountOnPackages`	Percentage discount on package purchases.
`AdditionEntitlement`	Entitlement to a rental addition, such as an insurance extra.
`FreeMinutes`	Free driving or rental minutes.

Shared benefit fields can restrict validity, number of rentals, applicable branches, applicable vehicle categories, applicable price type, and cost sources.

If benefits are present on a template, they are the preferred source of truth. Legacy fields such as value, discount, rentalRebate, and additionEntitlementId may still appear for compatibility.

Cost Sources And Price-Line Targeting

Cost sources let a benefit apply only to dedicated parts of a price instead of reducing the whole rental. This is useful for precise commercial offers such as “free unlock fee”, “discount only the time tier”, “cover only one addition”, or “reduce a surcharge but not the rental price”.

Benefits can use two related targeting fields:

Field	Use it for
`applicablePriceType`	Targets a price category such as `TIME_PRICE`, `DRIVING_PRICE`, `PARKING_PRICE`, `DISTANCE_PRICE`, `RESERVATION_PRICE`, or `UNLOCK_FEE`.
`costSources`	Targets specific source groups and source codes, grouped by `RENTAL`, `ADDITION`, or `SURCHARGE`.

Examples:

Offer	Possible targeting
Free unlock campaign	`applicablePriceType=UNLOCK_FEE`
Time-rate discount	`applicablePriceType=TIME_PRICE` or a `RENTAL` cost source that matches the configured time/tier source.
Addition entitlement or discount	`costSources` scoped to `ADDITION` and the addition code.
Surcharge waiver	`costSources` scoped to `SURCHARGE` and the surcharge source.

When costSources are set, the pricing engine applies these targeted benefits before broader benefits. This allows a targeted voucher to consume the intended line item before a general discount or value voucher reduces the remaining price.

Operator tools should expose cost-source targeting as an advanced configuration option, because it is powerful but easy to misunderstand if the operator cannot see which rental price lines, addition codes, or surcharge sources are affected.

Custom Tags, System Tags, And Eligibility

The API calls tags and labels annotations. In the back office, these are usually shown as custom tags and system tags. They can be assigned to users, business accounts, vehicles, bookings, and other objects depending on the workflow.

Promotions and benefits can use annotations to decide who can see, buy, redeem, or receive a benefit:

Field	Meaning
`guserRequiredAnnotationIds`	The customer must have these annotations to redeem or use the template.
`guserProhibitedAnnotationIds`	The customer must not have these annotations.
`requiredAnnotationIds`	Used on related models, such as additions, to require matching annotations.
`prohibitedAnnotationIds`	Used on related models to block matching annotations.

Examples:

Use case	Annotation behavior
Subscription only for an employee segment	Require a user custom tag; only matching users can see or purchase the subscription.
Promotion excluded for flagged users	Add a prohibited user annotation.
Vehicle promotion on selected vehicles	Apply the promotion only to vehicles carrying the configured annotation; the user can see the discount on the map for those vehicles.
Reward for a specific cohort	Require a system or custom tag before the reward can be granted.
Addition entitlement for selected customers	Use annotation gates so only matching users are entitled to the addition benefit.

Use annotation endpoints to discover and manage available tags:

Task	Endpoint
List annotations	`GET /annotations`
List only tags or labels	`GET /annotations?type=TAG` or `GET /annotations?type=LABEL`
Create annotation	`POST /annotations`
Get annotation	`GET /annotations/{id}`
Update annotation	`PUT /annotations/{id}`

For operator-facing UI labels, prefer “custom tags” and “system tags” where that matches the back-office vocabulary. Use “annotation” only when referring to the API object or field names.

Claim-Time Credit Vs Rental-Time Discount

Not every benefit affects the wallet in the same way:

Behavior	What happens
Claim-time credit	The customer receives wallet credit or balance when the voucher is claimed or granted.
Rental-time discount	The voucher remains conditional and reduces a rental price only when it applies to a rental.

This difference matters when explaining a customer’s balance. A balance update can show claim-time credit, while a rental rebate can show a rental-time application. Operator tools should not assume every promotion immediately changes the wallet.

Issued Voucher States

Constraint vouchers can have these states:

State	Meaning
`NOT_REDEEMED`	A single-use code exists but has not been redeemed yet.
`PENDING`	A referral-style voucher is waiting for a prerequisite.
`ACTIVE`	Voucher can apply.
`USED_UP`	Voucher benefit has been fully consumed.
`EXPIRED`	Voucher validity ended.
`CANCELED`	Voucher was canceled administratively.

Only active vouchers normally apply to rental pricing. Ride-pass renewal grace periods can create tenant-specific edge cases; review subscription and ride-pass settings when explaining expired-but-applied behavior.

Subscriptions

A subscription has two layers:

Concept	API shape	Meaning
Subscription plan	`ConstraintVoucherable` with `type=Subscription`	The catalog template: price, interval, and benefits.
User subscription	`UserSubscription`	The customer’s running subscription instance.

Subscription intervals include DAILY, WEEKLY, MONTHLY, FIRST_OF_MONTH, YEARLY, and FIRST_OF_YEAR.

User subscription state can be RENEWING, EXPIRED, SWITCHING, SWITCHED, or CANCELLED. Auto-renewal can be ACTIVE, INACTIVE, or FAILED. A failed auto-renewal should be shown as a payment or renewal problem rather than a normal cancellation.

Common Operator Workflows

Manage The Benefits Catalog

Use /voucherables for promotion, package, subscription, ride-pass, customer-care, reward, referral, and surcharge templates.

Task	Endpoint
Create template	`POST /voucherables`
Find template by code	`GET /voucherables/by-code/{code}`
Get template by ID	`GET /voucherables/{id}`
Update template	`PUT /voucherables/{id}`
Delete template	`DELETE /voucherables/{id}`
Activate template	`POST /voucherables/{id}/activate`
Deactivate template	`POST /voucherables/{id}/deactivate`

Activation validates the configuration and sets the template to ACTIVE. Keep draft or incomplete templates INACTIVE until branch scope, visibility, benefits, validity, and redeem limits are correct.

Create Promotion Codes

For reusable campaign templates, create a Promotion voucherable with a code and benefits.

For unique one-time redeemable codes, use the redeemable voucher endpoints:

Task	Endpoint
Create redeemable vouchers	`POST /vouchers/redeemable`
Create single-use constraint vouchers	`POST /vouchers/redeemable/constraint`
Review redeemable summary	`GET /vouchers/redeemable/summary`

Use single-use constraint vouchers when every code should be redeemable only once. POST /vouchers is deprecated and should not be used for new tooling.

Configure Packages And Paid Benefits

Packages are paid products. A customer buys the package and receives the configured credit or benefits. Packages can grant monetary credit, free minutes, discounts, addition entitlements, or other benefit combinations depending on configuration.

Use type=Package on /voucherables for new package tooling. The older /packages endpoints are deprecated and should be treated as legacy compatibility endpoints.

Package benefits are not pricing bundles. Pricing bundles define how rentals or bookings are priced. Packages define something a customer buys that can later affect wallet credit or price calculation.

Configure Subscription Plans

Use type=Subscription on /voucherables for new subscription plan tooling. Configure the interval, price, visibility, and benefits on the template.

Use annotation gates when a subscription should only be visible or purchasable for a selected customer segment. For example, an employee-only plan can require a user custom tag; users without that tag should not see or buy the subscription.

Legacy /subscriptions endpoints are deprecated. Use them only when maintaining older integrations that already depend on that endpoint shape.

Review And Cancel User Subscriptions

Use user subscription endpoints for customer support and billing review:

Task	Endpoint
List user subscriptions	`GET /user-subscriptions`
Cancel a user subscription	`POST /user-subscriptions/{userSubscriptionId}/cancel`

The cancel endpoint supports cancelBenefits=true to cancel all active vouchers granted by the subscription. Expose this option carefully because it can remove benefits the customer may still expect to use.

Grant Customer-Care Benefits

Customer-care templates are configured as CustomerCare voucherables. To apply them to a customer or business account, use:

Task	Endpoint
Apply to customer	`POST /customers/{userId}/apply-vouchers`
Apply to business account	`POST /groups/{groupId}/apply-vouchers`

These endpoints create all vouchers produced by the selected customer-care template. They are better for support workflows than manually creating singular vouchers.

Review Issued Vouchers

Use voucher endpoints when the operator needs to inspect what was issued to a customer or campaign.

Task	Endpoint
List vouchers	`GET /vouchers`
Get voucher by code	`GET /vouchers/by-code/{code}`
List constraint vouchers	`GET /vouchers/constraint-vouchers`
Cancel constraint voucher	`POST /vouchers/constraint-vouchers/{id}/cancel`

Use voucher state, validity, remaining value, remaining rental count, voucher type, and linked template to explain whether the customer can still use the benefit.

Configure Geofence Promotions And Surcharges

Geofence promotions and surcharges apply directly to rentals based on where the rental starts or ends.

These geofences are part of the voucherable configuration. If a custom tool needs to display promotional areas in search, campaign review, geo-event promotion screens, or map overlays, retrieve that information from /voucherables. Do not rely on the Areas API for promotional geofence display; Areas are the operational policy model, while voucherables are the commercial promotion and surcharge model.

Use applicableRentalType to define the rental phase:

Value	Meaning
`START_RENTAL`	Applies when the rental starts in the geofence.
`END_RENTAL`	Applies when the rental ends in the geofence.
`START_PLUS_END_RENTAL`	Can apply at start and end.
`START_OR_END_RENTAL`	Applies once if either condition is met.
`START_AND_END_RENTAL`	Applies only if both conditions are met.

Geofence surcharges are negative customer-facing benefits: they increase the rental price. Operator tools should label them as surcharges or fees, not as vouchers.

When combining commercial and operational overlays in one UI, label their source clearly. For example, an end-rental no-parking area comes from Areas, while a start-rental campaign discount or geofence surcharge comes from a voucherable.

Configure Vehicle Promotions

Vehicle promotions apply benefits to rentals on selected vehicles. They are useful when an operator wants to highlight or discount a subset of the fleet, such as vehicles in a campaign, vehicles that should be moved, or vehicles with a specific service or marketing tag.

Vehicle promotions can be combined with annotations/custom tags. If a vehicle has the required annotation, the promotion can apply and the end-user experience can show the discounted vehicle on the map. Operator tools should make the vehicle targeting visible so support teams can explain why one vehicle shows a discount and another does not.

Configure Targeted Cost-Source Benefits

Use cost-source targeting when the commercial offer should reduce only a specific price component:

Decide whether the benefit targets rental price, an addition, or a surcharge.
Set applicablePriceType when the target is a standard price category such as unlock fee, time, driving, parking, distance, or reservation.
Set costSources when the target is a specific configured source code.
Simulate or test with representative rentals before activating the template.
In support tooling, show the applied price line so operators can explain what was reduced.

Avoid using a broad value or discount benefit when the product intent is to discount only one price line. A broad voucher can reduce more of the rental than intended.

Most Relevant APIs

Area	Endpoint
Benefits catalog	`POST /voucherables`, `GET /voucherables/{id}`, `PUT /voucherables/{id}`, `DELETE /voucherables/{id}`
Template lookup	`GET /voucherables/by-code/{code}`
Template activation	`POST /voucherables/{id}/activate`, `POST /voucherables/{id}/deactivate`
Issued vouchers	`GET /vouchers`, `GET /vouchers/by-code/{code}`
Constraint vouchers	`GET /vouchers/constraint-vouchers`, `POST /vouchers/constraint-vouchers/{id}/cancel`
Redeemable codes	`POST /vouchers/redeemable`, `POST /vouchers/redeemable/constraint`, `GET /vouchers/redeemable/summary`
User subscriptions	`GET /user-subscriptions`, `POST /user-subscriptions/{userSubscriptionId}/cancel`
Customer-care grants	`POST /customers/{userId}/apply-vouchers`, `POST /groups/{groupId}/apply-vouchers`
Annotations/custom tags	`GET/POST /annotations`, `GET/PUT /annotations/{id}`
Legacy packages	`GET/POST /packages`, `GET/PATCH /packages/{id}`
Legacy subscriptions	`GET/POST /subscriptions`, `GET/PATCH/DELETE /subscriptions/{id}`

Permissions And Settings

Promotion and benefit management is permission-gated on the business unit that owns the promotion, package, subscription, ride pass, customer-care template, or issued voucher. A template can apply to one or more branches, but viewing or managing it requires permissions on the owning business unit. Operational branch access alone is not enough.

Separate permissions may apply for template management, voucher creation, customer-care credit, subscription review, and subscription cancellation. POST /vouchers/redeemable/constraint requires voucher creation permission.

For example, if a voucher is linked to Branch A and Branch A belongs to Business Unit B, an operator needs the relevant voucher permission on Business Unit B to see or create that voucher.

Settings can change how benefits behave. Examples include whether promotion redemption writes immediate balance credit or creates rental-time constraint vouchers, ride-pass renewal grace periods, package purchase behavior, and whether benefits are visible in the user app.

For custom tools:

Show branch scope and applicable vehicle categories before activation.
Show the owning business unit before listing, creating, activating, or deactivating templates.
Check business-unit permissions before showing voucher, package, subscription, ride-pass, customer-care, and redeemable-code actions.
Show cost-source and applicable-price-type targeting before activation.
Show required and prohibited custom/system tags before activation.
Treat customer-care credit and cancellation as support/admin actions.
Treat subscription cancellation with cancelBenefits=true as a high-impact action.
Do not expose root-only or internal-only settings. Root permissions are reserved for Wunder Mobility and can only be accessed by Wunder Mobility.

Implementation Notes

Use business labels in UIs: promotion, package, subscription, ride pass, customer-care credit, reward, referral benefit, surcharge.
Use voucherable only when mapping to the API request/response model.
Prefer /voucherables for new template management.
Use /voucherables to retrieve geofence promotion, geo-event promotion, and surcharge geometry for search or map display.
Treat /packages and /subscriptions as deprecated legacy endpoints.
Use benefits as the preferred source when benefits are present.
Use costSources and applicablePriceType to target specific price components instead of discounting the whole rental.
Use annotations/custom tags to control which users can see, buy, redeem, or receive a benefit.
Use vehicle annotations/custom tags to target vehicle promotions and explain map discounts.
Use issued voucher endpoints to explain customer-specific state and remaining value.
Use billing overview, balance updates, and applied rental rebates together when explaining why a customer paid a certain amount.

Review Notes

Confirm tenant-specific benefit behavior before exposing catalog writes to third-party tools. The safe action set depends on branch settings, promotion strategy, subscription setup, package purchase flows, and customer-care permission design.