public-api-docs

Operations API Vehicle Category Guide

Overview

Vehicle categories define how vehicles of a type behave in the platform. Every vehicle belongs to a vehicle category, and many operational decisions are configured at category level: bookability, pricing references, rental requirements, battery thresholds, charging behavior, supported actions, commands, attributes, and app/dashboard display properties.

Use vehicle category endpoints when building operator tooling for fleet configuration, category-specific vehicle behavior, or action/command discovery.

For vehicle inventory and fleet operations, see the Operations API Vehicle Guide.

Related reference: Operations API

Core Concepts

Vehicle Category

A vehicle category is the configuration template for a group of vehicles. It can describe a vehicle type such as car, scooter, bike, moped, cargo bike, or any operator-specific category.

Important category fields and configuration areas:

Area	Purpose
`name`	Operator-facing category name.
`parent`	Optional parent category used for inherited configuration.
`bookable`	Controls whether the category can be selected for booking/rental workflows.
`coreProperties`	Backend behavior such as pricing keys, rental requirements, battery thresholds, charging limits, speed settings, rental operation overrides, and lifecycle actions.
`sharedProperties`	Configuration shared across app/dashboard experiences, such as category features, parts, cancellation tags, or disabled rental operations.
`appProperties`	Customer app-specific category configuration.
`dashboardProperties`	Operator dashboard-specific category configuration.
`actions`	Vehicle actions/commands available for this category.
`vehicleAttributeIds`	Category-specific vehicle attributes.

Why Categories Matter

Do not treat vehicle categories as display labels only. Category configuration can influence:

Whether vehicles are visible or bookable.
Which start and end rental requirements apply.
Which payment pre-authorization or deposit behavior applies through rental requirements and pricing/payment configuration.
Which pricing configuration is used.
Which additions can be sold with rentals.
Which vehicle commands and actions are available.
Which battery thresholds determine LOW, CRITICAL, or charger-related availability.
Which service or maintenance actions are available.
Which rental operations are disabled or overridden.

Common Operator Workflows

List Vehicle Categories

Use GET /vehicles/categories for category lists used by normal operator tooling.

Use GET /vehicles/categories-management for administrative category-management screens. This endpoint is paginated and supports search/filtering.

Inspect One Vehicle Category

Use GET /vehicles/categories-management/{id} when an administrative tool needs the full category configuration.

Operator tools should inspect category configuration before assuming that a vehicle supports a command, action, addition, battery threshold, or rental requirement behavior.

Create Or Update Vehicle Categories

Use category-management endpoints:

Task	Endpoint
Create category	`POST /vehicles/categories-management`
Update category	`PATCH /vehicles/categories-management/{id}`
Delete category	`DELETE /vehicles/categories-management/{id}`
Reload category cache	`POST /vehicles/categories-management/reload`

Category changes can affect live vehicle availability, booking behavior, rental start/end checks, and command visibility. Treat category writes as administrative configuration changes and validate them in a staging environment before rolling them out broadly.

Retrieve Available Actions And Commands

Vehicle actions and commands are category-specific. A command/action is available only when it is configured for the vehicle category and the current operator has the required role/permission.

Use these endpoints:

Task	Endpoint
List available actions per category	`GET /vehicles/categories/actions`
List available commands per category	`GET /vehicles/categories/commands`
List action definitions	`GET /vehicles-management/actions`
Execute action	`POST /vehicles/execute-action/{actionId}`
Execute command	`POST /vehicles/execute-command`

For new tooling, prefer the action model. Actions can represent commands, activities, or composite activities and are easier to align with roles, vehicle categories, and operator workflows.

The older command list endpoint still exposes available commands per category. Use it only when the tool specifically needs command-level information. For user-facing operator workflows, showing configured actions is usually the better default.

Configure Commands And IoT Actions

Available vehicle actions/commands are configured on the vehicle category. This controls what an operator tool can show for vehicles in that category.

The low-level mapping between a platform command and the actual IoT/provider-specific action must be set up by Wunder Mobility. Operators can use the configured actions and commands exposed by the Operations API, but linking those commands to the underlying IoT integration is a one-time setup handled by Wunder Mobility.

This means a custom tool should:

Retrieve available actions/commands instead of hard-coding a command list.
Filter actions by the selected vehicle’s category.
Respect the current user’s permissions and roles.
Show only actions that are returned by the API for that category/user context.
Treat command execution as a high-impact physical-asset action.

Configure Availability And Battery Behavior

Vehicle category configuration can define battery and charging behavior, including:

Configuration	Why it matters
`socLevels`	Thresholds for `HIGH`, `MEDIUM`, `LOW`, and `CRITICAL` battery labels.
`ioTBatteryLevels`	Thresholds for raw IoT battery/voltage signals where configured.
`useIoTSoCLevel` / `useIoTBatteryLevel`	Whether availability and display should use IoT-provided values.
`ignoreSoC`	Whether SoC checks are skipped for availability.
`chargingLimit`	Target percentage for charger restrictions.
`stationChargingToggle`	Whether station charging behavior can block availability until the configured charging target is reached.

These settings influence whether a vehicle is ready to rent and which unavailability reason is shown in vehicle responses.

Configure Rental Behavior

Vehicle categories can reference rental-specific configuration:

Configuration	Why it matters
`rentalRequirementsKey`	Determines start/end rental requirements for vehicles in this category.
`priceCalcKey`	Connects the category to pricing calculation configuration.
`rentalAdditionPriceCalcs`	Maps rental addition codes to price calculation keys.
`preEndRentalActionsKey`	Defines actions that may run before rental end.
`disallowedRentalOperations`	Disables selected rental operations for this category.
`rentalOperationOverrides`	Overrides selected rental operation behavior such as timeouts.

For rental-specific behavior, also see the Operations API Rental Guide. For pricing configuration, see the Operations API Pricing Guide.

Most Relevant APIs

Task	Endpoint
List categories for operator tooling	`GET /vehicles/categories`
List available actions per category	`GET /vehicles/categories/actions`
List available commands per category	`GET /vehicles/categories/commands`
List categories for management	`GET /vehicles/categories-management`
Create category	`POST /vehicles/categories-management`
Get category by ID	`GET /vehicles/categories-management/{id}`
Update category	`PATCH /vehicles/categories-management/{id}`
Delete category	`DELETE /vehicles/categories-management/{id}`
Reload category cache	`POST /vehicles/categories-management/reload`
List action definitions	`GET /vehicles-management/actions`
Execute action	`POST /vehicles/execute-action/{actionId}`
Execute command	`POST /vehicles/execute-command`
Check current user’s permission	`GET /roles/assignments/exists`

Permissions And Settings

Vehicle category management is administrative configuration. Operators may be allowed to view categories but not create, update, delete, or reload them.

Common permission areas:

Workflow	Permission consideration
View categories	Vehicle/category read permission.
Manage categories	Vehicle category create/update/delete permissions.
View available actions	Vehicle action/category read permissions plus role visibility.
Execute actions or commands	Action/command execution permission and access to the vehicle branch.
Configure IoT mappings	Wunder Mobility internal setup; not an external operator-tool workflow.

Settings and category configuration work together. Settings can control broader tenant/branch behavior, while category properties control behavior for vehicles of that category. When building tools, read both the category and the relevant branch/settings configuration before deciding what a workflow supports.

Implementation Notes For Custom Tools

Always read the selected vehicle’s category before showing category-specific actions or commands.
Prefer GET /vehicles/categories/actions for new tools and use GET /vehicles/categories/commands only when command-level information is required.
Do not hard-code command availability. Available commands depend on vehicle category configuration, role visibility, and Wunder Mobility IoT setup.
Treat vehicle category updates as production configuration changes.
After changing category configuration, refresh affected vehicle/category data before offering dependent actions.
Do not expose root-only or Wunder Mobility internal IoT mapping workflows to external operators.

Review Notes

The following product decisions are reflected in this guide:

Vehicle categories are documented as a first-class Operations API concept because every vehicle has a category and category configuration affects many workflows.
Available actions and commands are documented as category-configured and permission/role-aware.
Linking platform commands to provider-specific IoT actions is documented as Wunder Mobility setup, not an external operator-tool workflow.
Pricing and pricing bundles are referenced as category-related configuration and documented in the Operations API Pricing Guide.