public-api-docs

Operations API Branches And Stations Guide

Overview

Branches and stations define the operational geography of a tenant. Use these endpoints when building operator tools for branch administration, branch-scoped search, station planning, booking station capacity, physical station infrastructure, or vehicle parking and docking workflows.

A branch is the main operational scope used across the Operations API. Vehicles, rentals, bookings, customers, pricing, settings, terms, tasks, invoices, KPIs, and permissions are usually evaluated in a branch context. Some branches are also business units, technically billable branches, which define the commercial scope for currency, tax, payment routing, balances, invoices, and benefit catalogs. Stations are location models inside the branch context and should be handled according to the station type and workflow.

Related reference: Operations API Operations API Guide Business Units And Billable Branches Guide Areas Guide Points Of Interest Guide Booking Guide Vehicle Guide Vehicle Category Guide Pricing Guide Error Codes

Core Concepts

Branches

Branches represent operational locations or branch-level configuration scopes. They can be organized in a hierarchy and can carry contact information, opening information, terms and conditions, UI settings, billing configuration, tax and currency configuration, and compatibility geometry fields for business areas and map overlays.

Important branch fields:

Field Meaning
id Branch identifier used by most Operations API endpoints.
name / code Human-readable and technical branch identifiers.
state Operational state, such as IN_PREPARATION, OPERATIONAL, MAINTENANCE, HIBERNATION, or OUT_OF_BUSINESS.
parent / children Branch hierarchy. Use child-branch flags intentionally on list endpoints.
businessArea Compatibility/read field for branch area geometry. Use the Areas API for new geofence management workflows.
mapOverlayProhibited Compatibility/read field for prohibited area overlay geometry. Use the Areas API for new prohibited/no-end-rental area workflows.
mapOverlayWarning Compatibility/read field for restricted or warning overlay geometry. Use the Areas API for new restricted/warning area workflows.
type / operationMode Whether the branch is used as a location/category scope and for on-demand or booking workflows.
visibility Whether the branch is public or private.
isBillable / billableBranchId Billing and invoicing scope.
termsAndConditionsId Terms users may need to accept for this branch.
currency / taxPercentage Financial context for pricing and invoicing.

Operator tools should treat branchId as more than a filter. It usually changes which vehicles, customers, terms, rental requirements, pricing bundles, settings, and permissions apply.

Business Units And Billable Branches

A business unit is the business-facing name for a billable branch. It owns commercial configuration such as currency, tax, payment routing, wallet balance scope, invoice scope, package/promotion/subscription catalog, and signup/referral benefit references.

Use this branch guide for operational geography. Use the Business Units And Billable Branches Guide when the workflow is about billing scope, payment setup, balances, invoices, vouchers, packages, subscriptions, or business-account defaults.

Branch concept Business-unit impact
Operational branch Defines where vehicles, rentals, bookings, stations, and permissions apply.
Non-billable branch Operational/organizational branch that points to a business unit for billing.
Billable branch/business unit Owns currency, tax, payment, wallet, invoice, and benefit catalog configuration.

Areas

Areas are geofenced rule zones that can affect parking, rental ending, speed limits, notices, and capacity. They are managed through the separate Operations API Areas Guide. Use areas for geofenced policy enforcement, not for station infrastructure or informational POI markers.

For new tools, Areas should be treated as the main management API for business-area and overlay configuration. Branch responses can still include businessArea, mapOverlayProhibited, and mapOverlayWarning because existing app and backend paths use those fields as a compatibility/read model. Do not build new branch write workflows around those fields unless a Wunder Mobility integration explicitly requires it.

Branch Hierarchy

Many list endpoints support includeChildren, includeChildBranches, or both. Use these flags deliberately:

Choice Use it when
Exact branch only The operator is working on one location or needs precise local counts.
Include child branches The operator is working from a regional, country, or parent branch view.
Mixed branch comparison The tool explicitly shows which branch each record belongs to.

Do not silently include child branches in action screens. For example, ending a rental, moving a vehicle, changing pricing, or modifying settings should clearly show the affected branch.

Compatible Branches

Compatible branches define allowed incoming and outgoing relationships between branches. The response exposes isIncoming and isOutgoing flags for each compatible branch.

Use compatible branch endpoints when a tool needs to manage cross-branch station or booking behavior, such as whether a branch can receive vehicles or send vehicles in one-way workflows.

Stations

The Operations API exposes multiple station concepts:

Station concept Endpoints Use it for
Stations /stations Branch-scoped station records such as virtual, docking, recommended, or promotion stations.
Booking stations /booking-stations Scheduled booking station planning, category capacity, expected vehicles, and conflicts.
Physical stations /physical-stations Physical infrastructure, slots, parking areas, vehicle docking, and vehicle parking.

These concepts overlap in product language, but they are separate API surfaces. Operator tools should choose the endpoint group that matches the workflow instead of treating all stations as the same resource.

Points Of Interest

Points of Interest (POIs) are map locations that can be displayed to end users or operators, such as parking locations, charging stations, service-relevant places, partner locations, or other points an operator wants to surface in the product.

POIs are not stations:

Concept Use it for
Station Pickup, return, booking capacity, docking, or parking infrastructure workflows.
POI Informational map markers with category, branch, display state, and optional rental visibility.

POIs are managed through the separate Points-Of-Interest APIs. See the Operations API Points Of Interest Guide for endpoint details, category setup, rental visibility, images, and localization.

Use POIs when the location should help users or operators understand the map, but should not control booking capacity, station parking, docking, or rental start/end validation.

Business Areas, Overlays, And End-Rental Rules

Branch responses can include business-area and map-overlay geometry. Rental start and end behavior can depend on that geometry, area policies, vehicle category rental requirements, and branch settings.

For example, an end-rental requirement can require the vehicle to be inside an allowed business or end-rental area, inside an allowed station area, or not in a prohibited/no-end-rental zone. A station or branch administration tool should make these spatial rules visible when operators configure or troubleshoot rentals.

Use the Areas Guide for geofence and overlay configuration. See the Rental Guide for start and end rental requirement context.

Common Operator Workflows

List And Search Branches

Use GET /branches-list to list branches.

Useful query parameters:

Parameter Use it for
searchText Find branches by name.
rootBranchId Limit results to a branch hierarchy.

Use GET /branches/{id} for a branch detail view. Set includeChildren=true when the tool needs to render or inspect the hierarchy below the selected branch.

Create Or Update A Branch

Use POST /branches to create a branch and PUT /branches/{id} to update an existing branch.

Branch changes can affect large parts of the tenant configuration. Before exposing branch writes in a custom tool, confirm the operator role is allowed to administer branch configuration and show the most relevant high-impact fields, such as state, parent branch, terms, currency, billing scope, and operation mode. Manage business areas and map overlays through the Areas API for new tooling.

Use PUT /branches/billable/{id} for billable branch updates. Billing scope changes should be restricted to administrative workflows because they can affect invoices, balances, payment routing, benefits, and reporting. For the business-unit concept and /business-units endpoints, see the Business Units And Billable Branches Guide.

Manage Compatible Branches

Use:

Task Endpoint
List compatible branches GET /branches/{id}/compatible-branches
Update compatible branches PUT /branches/{id}/compatible-branches

The update request contains compatible branch IDs and isIncoming / isOutgoing flags. Operator tools should show both directions explicitly. Incoming compatibility and outgoing compatibility are different decisions and should not be collapsed into one checkbox unless the tool intentionally sets both.

Work With General Stations

Use /stations for branch-scoped station records.

Task Endpoint
List stations GET /stations
Create station POST /stations
Get station detail GET /stations/{id}
Update station PATCH /stations/{id}
Delete station DELETE /stations/{id}

Important fields:

Field Meaning
type Station type, such as VIRTUAL, DOCKING, RECOMMENDED, or PROMOTION.
capacity Capacity for station-based workflows.
position / radius / area Spatial definition of the station.
visibility Whether the station is visible in the end-user app or service app.
state Whether the station is active or inactive.
validUntil Optional validity end.
reward Reward configuration where applicable.

Use GET /stations/{id} before updating or deleting a station so the operator can see current capacity, vehicles, visibility, and state.

Work With Booking Stations

Use booking station endpoints for scheduled booking planning. Booking stations expose category capacity, expected vehicles in a time window, and station conflicts.

Task Endpoint
List booking stations for a branch GET /booking-stations
List categories at a booking station GET /booking-stations/{bookingStationId}/vehicle-categories
List expected vehicles GET /booking-stations/{bookingStationId}/vehicles
List booking station conflicts GET /booking-stations/{bookingStationId}/conflicts

When using activeWithin, pass exactly two date-time values: start and end. Vehicle lists can include vehicles currently assigned to the station and vehicles moving through the station because of inbound or outbound bookings.

For booking creation and updates, use POST /bookings/availability/validate. The older booking-station availability endpoint is deprecated and should not be used for new tooling.

Work With Physical Stations

Use physical station endpoints for infrastructure workflows such as stations with slots, parking areas, docked vehicles, or reserved parking capacity.

Task Endpoint
List physical stations GET /physical-stations
Create physical station POST /physical-stations
Get physical station GET /physical-stations/{stationId}
Update physical station PATCH /physical-stations/{stationId}
List slots GET /physical-stations/{stationId}/slots
Create slot POST /physical-stations/{stationId}/slots
Update slot PATCH /physical-stations/{stationId}/slots/{slotId}
Delete slot DELETE /physical-stations/{stationId}/slots/{slotId}
Connect vehicle to slot POST /physical-stations/{stationId}/slots/{slotId}/connect-vehicle
Disconnect vehicle from slot POST /physical-stations/{stationId}/slots/{slotId}/disconnect-vehicle

Physical station state can be OPERATIONAL, TEMPORARY_CLOSED, PERMANENTLY_CLOSED, or IN_PREPARATION. Slot state can be OCCUPIED, VACANT, or OUT_OF_ORDER.

Manage Physical Station Parking Areas

A physical station can have a parking area with capacity, geometry, parked vehicles, and reserved parking count.

Task Endpoint
Get parking area GET /physical-stations/{stationId}/parking-area
Create parking area POST /physical-stations/{stationId}/parking-area
Update parking area PATCH /physical-stations/{stationId}/parking-area
Delete parking area DELETE /physical-stations/{stationId}/parking-area
List parked vehicles GET /physical-stations/{stationId}/parking-area/vehicles
Park one vehicle POST /physical-stations/{stationId}/parking-area/park-vehicle
Park multiple vehicles POST /physical-stations/{stationId}/parking-area/park-vehicles
Remove vehicle POST /physical-stations/{stationId}/parking-area/remove-vehicle

Use capacity = null for unlimited capacity when creating a parking area. When patching, send capacity = -1 to clear the capacity and make it unlimited. Do not send 0; zero is not allowed.

Troubleshoot Vehicle Availability By Location

When an operator asks why a vehicle is or is not available at a location, inspect the branch and station context together:

  1. Confirm the vehicle branch and vehicle category.
  2. Check whether the branch is operational and visible for the intended workflow.
  3. Check whether the vehicle is inside the relevant branch compatibility area, Area policy zone, or station area.
  4. Check vehicle service state, battery state, IoT state, and rental state.
  5. Check vehicle category settings and rental requirements for the branch.
  6. Check station capacity, physical station state, slot state, or booking station conflicts when station-based workflows are involved.

See the Vehicle Guide and Vehicle Category Guide for the vehicle-side checks.

Most Relevant APIs

Task Endpoint
Create branch POST /branches
List branches GET /branches-list
Get branch GET /branches/{id}
Update branch PUT /branches/{id}
Delete branch DELETE /branches/{id}
Update billable branch PUT /branches/billable/{id}
List compatible branches GET /branches/{id}/compatible-branches
Update compatible branches PUT /branches/{id}/compatible-branches
List stations GET /stations
Create station POST /stations
Get station detail GET /stations/{id}
Update station PATCH /stations/{id}
Delete station DELETE /stations/{id}
List booking stations GET /booking-stations
List booking station categories GET /booking-stations/{bookingStationId}/vehicle-categories
List booking station vehicles GET /booking-stations/{bookingStationId}/vehicles
List booking station conflicts GET /booking-stations/{bookingStationId}/conflicts
List physical stations GET /physical-stations
Create physical station POST /physical-stations
Get physical station GET /physical-stations/{stationId}
Update physical station PATCH /physical-stations/{stationId}
Manage physical station slots /physical-stations/{stationId}/slots
Manage physical station parking area /physical-stations/{stationId}/parking-area
Manage POIs Operations API Points Of Interest Guide

Permissions And Settings

Branch and station endpoints are permission-gated. Operators may be able to view a branch without being allowed to update branch configuration, billing scope, station infrastructure, or compatible branches.

Branch permissions usually cover operational workflows: vehicles, rentals, bookings, stations, tasks, damages, fleet actions, and branch visibility. Commercial workflows can use the linked business unit instead. If a branch points to a business unit, voucher, package, subscription, balance, invoice, payment, and settlement permissions are usually evaluated on that business unit. See the Business Units And Billable Branches Guide for the full model.

For custom tools:

Area Guidance
Branch visibility Use the authenticated operator’s branch permissions. Do not assume access to all tenant branches.
Branch writes Restrict to administrative users. Branch writes affect many downstream workflows.
Billable branch writes Treat as finance-sensitive business-unit configuration.
Station writes Restrict by station-management permissions and branch access.
Physical station writes Restrict to infrastructure or operations-admin workflows.
Commercial resources linked to a branch Check business-unit permissions for vouchers, packages, subscriptions, balances, invoices, payments, and settlements.
Root permissions Root permissions are reserved for Wunder Mobility and can only be accessed by Wunder Mobility.

Settings can also change behavior by branch and vehicle category. For example, station workflows, rental requirements, pricing behavior, and feature visibility can be enabled or disabled differently across branches. Use GET /settings for effective settings required by an operator tool and /settings-management only for administrative configuration workflows.

Implementation Notes

Review Notes

Confirm tenant-specific configuration with Wunder Mobility before exposing branch writes, compatible branch writes, or physical station infrastructure writes to third-party operator tools. These endpoints are suitable for administrative tooling, but the safe action set depends on the operator role model and product configuration.